README.Coding

   1 ##
   2 ## Coding conventions in the Samba 3.0 tree
   3 ##
   4
   5 ===========
   6 Quick Start
   7 ===========
   8
   9 Coding style guidelines are about reducing the number of unnecessary
  10 reformatting patches and making things easier developers to work together.
  11 You don't have to like them or even agree with them, but once put in place
  12 we all have to abide by them (or vote to change them).  However, coding
  13 style should never outweigh coding itself and so the the guidelines
  14 described here are hopefully easier enough to follow as they are very
  15 common and supported by tools and editors.
  16
  17 The basic style, also mentioned in the SAMBA_4_0/prog_guide.txt is the
  18 Linux kernel coding style (See Documentation/CodingStyle in the kernel
  19 source tree).  The closely matches what most Samba developers use already
  20 anyways.
  21
  22 But to save you the trouble of reading the Linux kernel style guide, here
  23 are the highlights.
  24
  25
  26 * Maximum Line Width is 80 Characters
  27   The reason is not for people with low-res screens but rather sticking
  28   to 80 columns prevents you from easily nesting more than one level of
  29   if statements or other code blocks.  Use source/script/count_80_col.pl
  30   to check your changes.
  31
  32 * Use 8 Space Tabs to Indent
  33   No whitespace filler.
  34
  35 * No Trailing Whitespace
  36   Use source/script/strip_trail_ws.pl to clean you files before committing.
  37
  38 * Follow the K&R guidelines.  We won't go throw them all here.  You have
  39   a copy of "The C Programming Language" anyways right?  You can also use
  40   the format_indent.sh script found in source/script/ if all else fails.
  41
  42
  43
  44 ============
  45 Editor Hints
  46 ============
  47
  48 Emacs
  49 -----
  50 Add the follow to your $HOME/.emacs file:
  51
  52   (add-hook 'c-mode-hook
  53         (lambda ()
  54                 (c-set-style "linux")
  55                 (c-toggle-auto-state)))
  56
  57
  58 Vi
  59 --
  60 (Thanks to SATOH Fumiyasu <fumiyas@osstech.jp> for these hints):
  61
  62 For the basic vi editor including with all variants of *nix, add the
  63 following to $HOME/.exrc:
  64
  65   set tabstop=8
  66   set shiftwidth=8
  67
  68 For Vim, the following settings in $HOME/.vimrc will also deal with
  69 displaying trailing whitespace:
  70
  71   if has("syntax") && (&t_Co > 2 || has("gui_running"))
  72         syntax on
  73         function! ActivateInvisibleCharIndicator()
  74                 syntax match TrailingSpace "[ \t]\+$" display containedin=ALL
  75                 highlight TrailingSpace ctermbg=Red
  76         endf
  77         autocmd BufNewFile,BufRead * call ActivateInvisibleCharIndicator()
  78   endif
  79
  80
  81 =========================
  82 FAQ & Statement Reference
  83 =========================
  84
  85 Comments
  86 --------
  87
  88 Comments should always use the standard C syntax.  I.e. /* ... */.  C++
  89 style comments are not currently allowed.
  90
  91
  92 Indention & Whitespace & 80 columns
  93 -----------------------------------
  94
  95 To avoid confusion, indentations are to be 8 character with tab (not
  96 8 ' ' characters.  When wrapping parameters for function calls,
  97 alignment parameter list with the first parameter on the previous line.
  98 Use tabs to get as close as possible and then fill in the final 7
  99 characters or less with whitespace.  For example,
 100
 101         var1 = foo(arg1, arg2,
 102                    arg3);
 103
 104 The previous example is intended to illustrate alignment of function
 105 parameters across lines and not as encourage for gratuitous line
 106 splitting.  Never split a line before columns 70 - 79 unless you
 107 have a really good reason.  Be smart about formatting.
 108
 109
 110 If, switch, & Code blocks
 111 -------------------------
 112
 113 Always follow an 'if' keyword with a space but don't include additional
 114 spaces following or preceding the parentheses in the conditional.
 115 This is good:
 116
 117         if (x == 1)
 118
 119 This is bad:
 120
 121         if ( x == 1 )
 122
 123 Yes we have a lot of code that uses the second form and we are trying
 124 to clean it up without being overly intrusive.
 125
 126 Note that this is a rule about parentheses following keywords and not
 127 functions.  Don't insert a space between the name and left parentheses when
 128 invoking functions.
 129
 130 Braces for code blocks used by for, if, switch, while, do..while, etc...
 131 should begin on the same line as the statement keyword and end on a line
 132 of their own.  NOTE: Functions are different and the beginning left brace
 133 should begin on a line of its own.
 134
 135 If the beginning statement has to be broken across lines due to length,
 136 the beginning brace should be on a line of its own.
 137
 138 The exception to the ending rule is when the closing brace is followed by
 139 another language keyword such as else or the closing while in a do..while
 140 loop.
 141
 142 Good examples:
 143
 144         if (x == 1) {
 145                 printf("good\n");
 146         }
 147
 148         for (x=1;
 149              x<10;
 150              x++)
 151         {
 152                 print("%d\n", x);
 153         }
 154
 155         do {
 156                 printf("also good\n");
 157         } while (1);
 158
 159 Bad examples:
 160
 161         while (1)
 162         {
 163                 print("I'm in a loop!\n"); }
 164
 165
 166 Goto
 167 ----
 168
 169 While many people have been academically taught that goto's are fundamentally
 170 evil, then can greatly enhance readability and reduce memory leaks when used
 171 as the single exit point from a function.  But in no Samba world what so ever
 172 is a goto outside of a function or block of code a good idea.
 173
 174 Good Examples:
 175
 176 int function foo(int y)
 177 {
 178         int *z = NULL;
 179         int ret = 0;
 180
 181         if ( y < 10 ) {
 182                 z = malloc(sizeof(int)*y);
 183                 if (!z) {
 184                         ret = 1;
 185                         goto done;
 186                 }
 187         }
 188
 189         print("Allocated %d elements.\n", y);
 190
 191  done:
 192         if (z)
 193                 free(z);
 194
 195         return ret;
 196 }
 197
 198
 199 Checking Pointer Values
 200 -----------------------
 201
 202 When invoking functions that return pointer values, either of the following
 203 are acceptable.  Use you best judgement and choose the more readable option.
 204 Remember that many other people will review it.
 205
 206         if ((x = malloc(sizeof(short)*10)) == NULL ) {
 207                 fprintf(stderr, "Unable to alloc memory!\n");
 208         }
 209
 210 or
 211
 212         x = malloc(sizeof(short)*10);
 213         if (!x) {
 214                 fprintf(stderr, "Unable to alloc memory!\n");
 215         }