README.Coding

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