From e00bdb4a323b60ced500df59071d2a940b976ae9 Mon Sep 17 00:00:00 2001
From: Shehjar Tikoo <shehjart@zresearch.com>
Date: Wed, 8 Apr 2009 02:28:16 -0700
Subject: Coding Style: Add a few points

Signed-off-by: Anand V. Avati <avati@amp.gluster.com>
---
 doc/coding-standard.tex | 38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

(limited to 'doc')

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;
-- 
cgit