summaryrefslogtreecommitdiffstats log msg author committer range
path: root/doc/coding-standard.tex
diff options
 context: 12345678910152025303540 space: includeignore mode: unifiedssdiffstat only
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.texindex ed9d920..92f799c 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;