PC Oota Edits.

[kai/samba-autobuild/.git] / README.Coding

diff --git a/README.Coding b/README.Coding
index 2e7dd2f3f245991caa75c17d783a92bd85113f62..ddeacc934a66e5be4c0fe6371ab7f20a468922b3 100644 (file)
--- a/README.Coding
+++ b/README.Coding
@@ -15,9 +15,10 @@ style should never outweigh coding itself and so the guidelines
 described here are hopefully easy enough to follow as they are very
 common and supported by tools and editors.
 
-The basic style, also mentioned in prog_guide4.txt, is the Linux kernel coding 
-style (See Documentation/CodingStyle in the kernel source tree). This closely 
-matches what most Samba developers use already anyways.
+The basic style, also mentioned in prog_guide4.txt, is the Linux kernel coding
+style (See Documentation/CodingStyle in the kernel source tree). This closely
+matches what most Samba developers use already anyways, with a few exceptions as
+mentioned below.
 
 But to save you the trouble of reading the Linux kernel style guide, here
 are the highlights.
@@ -125,23 +126,24 @@ This is bad:
 
        if ( x == 1 )
 
-Yes we have a lot of code that uses the second form and we are trying 
+Yes we have a lot of code that uses the second form and we are trying
 to clean it up without being overly intrusive.
 
 Note that this is a rule about parentheses following keywords and not
-functions.  Don't insert a space between the name and left parentheses when 
+functions.  Don't insert a space between the name and left parentheses when
 invoking functions.
 
 Braces for code blocks used by for, if, switch, while, do..while, etc.
-should begin on the same line as the statement keyword and end on a line 
-of their own.  NOTE: Functions are different and the beginning left brace
-should begin on a line of its own.
+should begin on the same line as the statement keyword and end on a line
+of their own. You should always include braces, even if the block only
+contains one statement.  NOTE: Functions are different and the beginning left
+brace should begin on a line of its own.
 
 If the beginning statement has to be broken across lines due to length,
 the beginning brace should be on a line of its own.
 
-The exception to the ending rule is when the closing brace is followed by 
-another language keyword such as else or the closing while in a do..while 
+The exception to the ending rule is when the closing brace is followed by
+another language keyword such as else or the closing while in a do..while
 loop.
 
 Good examples::
@@ -150,13 +152,17 @@ Good examples::
                printf("good\n");
        }
 
-       for (x=1;
-            x<10;
-            x++)
-       {
+       for (x=1; x<10; x++) {
                print("%d\n", x);
        }
 
+       for (really_really_really_really_long_var_name=0;
+            really_really_really_really_long_var_name<10;
+            really_really_really_really_long_var_name++)
+       {
+               print("%d\n", really_really_really_really_long_var_name);
+       }
+
        do {
                printf("also good\n");
        } while (1);
@@ -166,7 +172,17 @@ Bad examples::
        while (1)
        {
                print("I'm in a loop!\n"); }
-       
+
+       for (x=1;
+            x<10;
+            x++)
+       {
+               print("no good\n");
+       }
+
+       if (i < 10)
+               print("I should be in braces.\n");
+
 
 Goto
 ----
@@ -183,7 +199,7 @@ Good Examples::
                int *z = NULL;
                int ret = 0;
 
-               if ( y < 10 ) {
+               if (y < 10) {
                        z = malloc(sizeof(int)*y);
                        if (!z) {
                                ret = 1;
@@ -233,3 +249,37 @@ new code should adhere to the following conventions:
   * Booleans are of type "bool" (not BOOL)
   * Boolean values are "true" and "false" (not True or False)
   * Exact width integers are of type [u]int[8|16|32|64]_t
+
+
+Typedefs
+--------
+
+Samba tries to avoid "typedef struct { .. } x_t;", we always use
+"struct x { .. };". We know there are still those typedefs in the code,
+but for new code, please don't do that.
+
+Make use of helper variables
+----------------------------
+
+Please try to avoid passing function calls as function parameters
+in new code. This makes the code much easier to read and
+it's also easier to use the "step" command within gdb.
+
+Good Example::
+
+       char *name;
+
+       name = get_some_name();
+       if (name == NULL) {
+               ...
+       }
+
+       ret = some_function_my_name(name);
+       ...
+
+
+Bad Example::
+
+       ret = some_function_my_name(get_some_name());
+       ...
+