summaryrefslogtreecommitdiffstats
path: root/doc/coding-standard.tex
diff options
context:
space:
mode:
Diffstat (limited to 'doc/coding-standard.tex')
-rw-r--r--doc/coding-standard.tex38
1 files changed, 31 insertions, 7 deletions
diff --git a/doc/coding-standard.tex b/doc/coding-standard.tex
index ed9d920eccf..92f799c013f 100644
--- a/doc/coding-standard.tex
+++ b/doc/coding-standard.tex
@@ -199,10 +199,14 @@ commented out code in the codebase.
There must be only one exit out of a function. \texttt{UNWIND} and return
should happen at only point in the function.
-\section*{$\bullet$ Keep functions small}
-Try to keep functions small. Two to three screenfulls (80 lines per screen) is
-considered a reasonable limit. If a function is very long, try splitting it
-into many little helper functions.
+\section*{$\bullet$ Function length or Keep functions small}
+We live in the UNIX-world where modules do one thing and do it well.
+This rule should apply to our functions also. If a function is very long, try splitting it
+into many little helper functions. The question is, in a coding
+spree, how do we know a function is long and unreadable. One rule of
+thumb given by Linus Torvalds is that, a function should be broken-up
+if you have 4 or more levels of indentation going on for more than 3-4
+lines.
\vspace{2ex}
\textsl{Example for a helper function}:
@@ -215,6 +219,28 @@ into many little helper functions.
}
\end{verbatim}
+\section*{$\bullet$ Defining functions as static}
+Define internal functions as static only if you're
+very sure that there will not be a crash(..of any kind..) emanating in
+that function. If there is even a remote possibility, perhaps due to
+pointer derefering, etc, declare the function as non-static. This
+ensures that when a crash does happen, the function name shows up the
+in the back-trace generated by libc. However, doing so has potential
+for polluting the function namespace, so to avoid conflicts with other
+components in other parts, ensure that the function names are
+prepended with a prefix that identify the component to which it
+belongs. For eg. non-static functions in io-threads translator start
+with iot\_.
+
+\section*{$\bullet$ Ensure function calls wrap around after
+80-columns.}
+Place remaining arguments on the next line if needed.
+
+\section*{$\bullet$ Functions arguments and function definition}
+Place all the arguments of a function definition on the same line
+until the line goes beyond 80-cols. Arguments that extend beyind
+80-cols should be placed on the next line.
+
\section*{Style issues}
\subsection*{Brace placement}
@@ -299,9 +325,7 @@ that has occured and do appropriate cleanup.
\begin{verbatim}
int32_t
-sample_fop (call_frame_t *frame,
- xlator_t *this,
- ...)
+sample_fop (call_frame_t *frame, xlator_t *this, ...)
{
char * var1 = NULL;
int32_t op_ret = -1;