diff options
Diffstat (limited to 'doc/coding-standard.tex')
| -rw-r--r-- | doc/coding-standard.tex | 38 |
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; |