Add NetGetJoinableOUs() to libnetapi (incl. example).
[nivanova/samba-autobuild/.git] / README.Coding
index 60ea1c6f1fc347ca865c7d70acf284fd6b09fd24..fd52dbe890d6b870b7bcfa77b528224debc762f2 100644 (file)
@@ -59,14 +59,14 @@ Vi
 --
 (Thanks to SATOH Fumiyasu <fumiyas@osstech.jp> for these hints):
 
-For the basic vi eitor including with all variants of *nix, add the 
+For the basic vi editor including with all variants of *nix, add the 
 following to $HOME/.exrc:
 
   set tabstop=8
   set shiftwidth=8
 
 For Vim, the following settings in $HOME/.vimrc will also deal with 
-disaplaying trailing whitespace:
+displaying trailing whitespace:
 
   if has("syntax") && (&t_Co > 2 || has("gui_running"))
        syntax on
@@ -76,12 +76,161 @@ disaplaying trailing whitespace:
        endf
        autocmd BufNewFile,BufRead * call ActivateInvisibleCharIndicator()
   endif
+  " Show tabs, trailing whitespace, and continued lines visually
+  set list listchars=tab:»·,trail:·,extends:…
 
+  " highlight overly long lines same as TODOs.
+  set textwidth=80
+  autocmd BufNewFile,BufRead *.c,*.h exec 'match Todo /\%>' . &textwidth . 'v.\+/'
 
-===================
-Statement Reference
-===================
 
-To be filled later in as needed.
+=========================
+FAQ & Statement Reference
+=========================
 
+Comments
+--------
 
+Comments should always use the standard C syntax.  I.e. /* ... */.  C++ 
+style comments are not currently allowed.
+
+
+Indention & Whitespace & 80 columns
+-----------------------------------
+
+To avoid confusion, indentations are to be 8 character with tab (not 
+8 ' ' characters.  When wrapping parameters for function calls, 
+alignment parameter list with the first parameter on the previous line.
+Use tabs to get as close as possible and then fill in the final 7 
+characters or less with whitespace.  For example,
+
+       var1 = foo(arg1, arg2,
+                  arg3);
+
+The previous example is intended to illustrate alignment of function 
+parameters across lines and not as encourage for gratuitous line 
+splitting.  Never split a line before columns 70 - 79 unless you
+have a really good reason.  Be smart about formatting.
+
+
+If, switch, & Code blocks
+-------------------------
+
+Always follow an 'if' keyword with a space but don't include additional
+spaces following or preceding the parentheses in the conditional.
+This is good:
+
+       if (x == 1)
+
+This is bad:
+
+       if ( x == 1 )
+
+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 
+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.
+
+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 
+loop.
+
+Good examples:
+
+       if (x == 1) {
+               printf("good\n");
+       }
+
+       for (x=1;
+            x<10;
+            x++)
+       {
+               print("%d\n", x);
+       }
+
+       do {
+               printf("also good\n");
+       } while (1);
+
+Bad examples:
+
+       while (1)
+       {
+               print("I'm in a loop!\n"); }
+       
+
+Goto
+----
+
+While many people have been academically taught that goto's are fundamentally
+evil, then can greatly enhance readability and reduce memory leaks when used
+as the single exit point from a function.  But in no Samba world what so ever 
+is a goto outside of a function or block of code a good idea.
+
+Good Examples:
+
+int function foo(int y)
+{
+       int *z = NULL;
+       int ret = 0;
+
+       if ( y < 10 ) {
+               z = malloc(sizeof(int)*y);
+               if (!z) {
+                       ret = 1;
+                       goto done;
+               }
+       }
+
+       print("Allocated %d elements.\n", y);
+
+ done: 
+       if (z)
+               free(z);
+
+       return ret;
+}
+
+
+Checking Pointer Values
+-----------------------
+
+When invoking functions that return pointer values, either of the following 
+are acceptable.  Use you best judgement and choose the more readable option.
+Remember that many other people will review it.
+
+       if ((x = malloc(sizeof(short)*10)) == NULL ) {
+               fprintf(stderr, "Unable to alloc memory!\n");
+       }
+
+or
+
+       x = malloc(sizeof(short)*10);
+       if (!x) {
+               fprintf(stderr, "Unable to alloc memory!\n");
+       }
+
+
+Primitive Data Types
+--------------------
+
+Samba has large amounts of historical code which makes use of data types 
+commonly supported by the C99 standard. However, at the time such types 
+as boolean and exact width integers did not exist and Samba developers 
+were forced to provide their own.  Now that these types are guaranteed to 
+be available either as part of the compiler C99 support or from lib/replace/, 
+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