1Coding conventions in the Samba tree 2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 4.. contents:: 5 6=========== 7Quick Start 8=========== 9 10Coding style guidelines are about reducing the number of unnecessary 11reformatting patches and making things easier for developers to work together. 12You don't have to like them or even agree with them, but once put in place 13we all have to abide by them (or vote to change them). However, coding 14style should never outweigh coding itself and so the guidelines 15described here are hopefully easy enough to follow as they are very 16common and supported by tools and editors. 17 18The basic style, also mentioned in prog_guide4.txt, is the Linux kernel coding 19style (See Documentation/CodingStyle in the kernel source tree). This closely 20matches what most Samba developers use already anyways. 21 22But to save you the trouble of reading the Linux kernel style guide, here 23are 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 source3/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 source3/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 source3/script/ if all else fails. 40 41 42 43============ 44Editor Hints 45============ 46 47Emacs 48----- 49Add 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 57Vi 58-- 59(Thanks to SATOH Fumiyasu <fumiyas@osstech.jp> for these hints): 60 61For the basic vi editor included with all variants of \*nix, add the 62following to $HOME/.exrc: 63 64 set tabstop=8 65 set shiftwidth=8 66 67For Vim, the following settings in $HOME/.vimrc will also deal with 68displaying 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========================= 87FAQ & Statement Reference 88========================= 89 90Comments 91-------- 92 93Comments should always use the standard C syntax. C++ 94style comments are not currently allowed. 95 96 97Indention & Whitespace & 80 columns 98----------------------------------- 99 100To avoid confusion, indentations are to be 8 character with tab (not 1018 ' ' characters. When wrapping parameters for function calls, 102align the parameter list with the first parameter on the previous line. 103Use tabs to get as close as possible and then fill in the final 7 104characters or less with whitespace. For example, 105 106 var1 = foo(arg1, arg2, 107 arg3); 108 109The previous example is intended to illustrate alignment of function 110parameters across lines and not as encourage for gratuitous line 111splitting. Never split a line before columns 70 - 79 unless you 112have a really good reason. Be smart about formatting. 113 114 115If, switch, & Code blocks 116------------------------- 117 118Always follow an 'if' keyword with a space but don't include additional 119spaces following or preceding the parentheses in the conditional. 120This is good: 121 122 if (x == 1) 123 124This is bad: 125 126 if ( x == 1 ) 127 128Yes we have a lot of code that uses the second form and we are trying 129to clean it up without being overly intrusive. 130 131Note that this is a rule about parentheses following keywords and not 132functions. Don't insert a space between the name and left parentheses when 133invoking functions. 134 135Braces for code blocks used by for, if, switch, while, do..while, etc. 136should begin on the same line as the statement keyword and end on a line 137of their own. NOTE: Functions are different and the beginning left brace 138should begin on a line of its own. 139 140If the beginning statement has to be broken across lines due to length, 141the beginning brace should be on a line of its own. 142 143The exception to the ending rule is when the closing brace is followed by 144another language keyword such as else or the closing while in a do..while 145loop. 146 147Good 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 164Bad examples:: 165 166 while (1) 167 { 168 print("I'm in a loop!\n"); } 169 170 171Goto 172---- 173 174While many people have been academically taught that goto's are fundamentally 175evil, they can greatly enhance readability and reduce memory leaks when used 176as the single exit point from a function. But in no Samba world what so ever 177is a goto outside of a function or block of code a good idea. 178 179Good 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 204Checking Pointer Values 205----------------------- 206 207When invoking functions that return pointer values, either of the following 208are acceptable. Use you best judgement and choose the more readable option. 209Remember 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 215or:: 216 217 x = malloc(sizeof(short)*10); 218 if (!x) { 219 fprintf(stderr, "Unable to alloc memory!\n"); 220 } 221 222 223Primitive Data Types 224-------------------- 225 226Samba has large amounts of historical code which makes use of data types 227commonly supported by the C99 standard. However, at the time such types 228as boolean and exact width integers did not exist and Samba developers 229were forced to provide their own. Now that these types are guaranteed to 230be available either as part of the compiler C99 support or from lib/replace/, 231new 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 236