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   " Show tabs, trailing whitespace, and continued lines visually
  80   set list listchars=tab:»·,trail:·,extends:…
  81
  82   " highlight overly long lines same as TODOs.
  83   set textwidth=80
  84   autocmd BufNewFile,BufRead *.c,*.h exec 'match Todo /\%>' . &textwidth . 'v.\+/'
  85
  86
  87 =========================
  88 FAQ & Statement Reference
  89 =========================
  90
  91 Comments
  92 --------
  93
  94 Comments should always use the standard C syntax.  I.e. /* ... */.  C++
  95 style comments are not currently allowed.
  96
  97
  98 Indention & Whitespace & 80 columns
  99 -----------------------------------
 100
 101 To avoid confusion, indentations are to be 8 character with tab (not
 102 8 ' ' characters.  When wrapping parameters for function calls,
 103 alignment parameter list with the first parameter on the previous line.
 104 Use tabs to get as close as possible and then fill in the final 7
 105 characters or less with whitespace.  For example,
 106
 107         var1 = foo(arg1, arg2,
 108                    arg3);
 109
 110 The previous example is intended to illustrate alignment of function
 111 parameters across lines and not as encourage for gratuitous line
 112 splitting.  Never split a line before columns 70 - 79 unless you
 113 have a really good reason.  Be smart about formatting.
 114
 115
 116 If, switch, & Code blocks
 117 -------------------------
 118
 119 Always follow an 'if' keyword with a space but don't include additional
 120 spaces following or preceding the parentheses in the conditional.
 121 This is good:
 122
 123         if (x == 1)
 124
 125 This is bad:
 126
 127         if ( x == 1 )
 128
 129 Yes we have a lot of code that uses the second form and we are trying
 130 to clean it up without being overly intrusive.
 131
 132 Note that this is a rule about parentheses following keywords and not
 133 functions.  Don't insert a space between the name and left parentheses when
 134 invoking functions.
 135
 136 Braces for code blocks used by for, if, switch, while, do..while, etc...
 137 should begin on the same line as the statement keyword and end on a line
 138 of their own.  NOTE: Functions are different and the beginning left brace
 139 should begin on a line of its own.
 140
 141 If the beginning statement has to be broken across lines due to length,
 142 the beginning brace should be on a line of its own.
 143
 144 The exception to the ending rule is when the closing brace is followed by
 145 another language keyword such as else or the closing while in a do..while
 146 loop.
 147
 148 Good examples:
 149
 150         if (x == 1) {
 151                 printf("good\n");
 152         }
 153
 154         for (x=1;
 155              x<10;
 156              x++)
 157         {
 158                 print("%d\n", x);
 159         }
 160
 161         do {
 162                 printf("also good\n");
 163         } while (1);
 164
 165 Bad examples:
 166
 167         while (1)
 168         {
 169                 print("I'm in a loop!\n"); }
 170
 171
 172 Goto
 173 ----
 174
 175 While many people have been academically taught that goto's are fundamentally
 176 evil, then can greatly enhance readability and reduce memory leaks when used
 177 as the single exit point from a function.  But in no Samba world what so ever
 178 is a goto outside of a function or block of code a good idea.
 179
 180 Good Examples:
 181
 182 int function foo(int y)
 183 {
 184         int *z = NULL;
 185         int ret = 0;
 186
 187         if ( y < 10 ) {
 188                 z = malloc(sizeof(int)*y);
 189                 if (!z) {
 190                         ret = 1;
 191                         goto done;
 192                 }
 193         }
 194
 195         print("Allocated %d elements.\n", y);
 196
 197  done:
 198         if (z)
 199                 free(z);
 200
 201         return ret;
 202 }
 203
 204
 205 Checking Pointer Values
 206 -----------------------
 207
 208 When invoking functions that return pointer values, either of the following
 209 are acceptable.  Use you best judgement and choose the more readable option.
 210 Remember that many other people will review it.
 211
 212         if ((x = malloc(sizeof(short)*10)) == NULL ) {
 213                 fprintf(stderr, "Unable to alloc memory!\n");
 214         }
 215
 216 or
 217
 218         x = malloc(sizeof(short)*10);
 219         if (!x) {
 220                 fprintf(stderr, "Unable to alloc memory!\n");
 221         }
 222
 223
 224 Primitive Data Types
 225 --------------------
 226
 227 Samba has large amounts of historical code which makes use of data types
 228 commonly supported by the C99 standard. However, at the time such types
 229 as boolean and exact width integers did not exist and Samba developers
 230 were forced to provide their own.  Now that these types are guaranteed to
 231 be available either as part of the compiler C99 support or from lib/replace/,
 232 new code should adhere to the following conventions:
 233
 234   * Booleans are of type "bool" (not BOOL)
 235   * Boolean values are "true" and "false" (not True or False)
 236   * Exact width integers are of type [u]int[8|16|32|64]_t