diff options
Diffstat (limited to 'README.Coding')
| -rw-r--r-- | README.Coding | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/README.Coding b/README.Coding new file mode 100644 index 0000000000..52ecf0e102 --- /dev/null +++ b/README.Coding @@ -0,0 +1,236 @@ +## +## Coding conventions in the Samba 3 tree +## + +=========== +Quick Start +=========== + +Coding style guidelines are about reducing the number of unnecessary +reformatting patches and making things easier for developers to work together. +You don't have to like them or even agree with them, but once put in place +we all have to abide by them (or vote to change them). However, coding +style should never outweigh coding itself and so the the guidelines +described here are hopefully easy enough to follow as they are very +common and supported by tools and editors. + +The basic style, also mentioned in the SAMBA_4_0/prog_guide.txt is the +Linux kernel coding style (See Documentation/CodingStyle in the kernel +source tree). The closely matches what most Samba developers use already +anyways. + +But to save you the trouble of reading the Linux kernel style guide, here +are the highlights. + + +* Maximum Line Width is 80 Characters + The reason is not for people with low-res screens but rather sticking + to 80 columns prevents you from easily nesting more than one level of + if statements or other code blocks. Use source/script/count_80_col.pl + to check your changes. + +* Use 8 Space Tabs to Indent + No whitespace filler. + +* No Trailing Whitespace + Use source/script/strip_trail_ws.pl to clean you files before committing. + +* Follow the K&R guidelines. We won't go throw them all here. You have + a copy of "The C Programming Language" anyways right? You can also use + the format_indent.sh script found in source/script/ if all else fails. + + + +============ +Editor Hints +============ + +Emacs +----- +Add the follow to your $HOME/.emacs file: + + (add-hook 'c-mode-hook + (lambda () + (c-set-style "linux") + (c-toggle-auto-state))) + + +Vi +-- +(Thanks to SATOH Fumiyasu <fumiyas@osstech.jp> for these hints): + +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 +displaying trailing whitespace: + + if has("syntax") && (&t_Co > 2 || has("gui_running")) + syntax on + function! ActivateInvisibleCharIndicator() + syntax match TrailingSpace "[ \t]\+$" display containedin=ALL + highlight TrailingSpace ctermbg=Red + 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.\+/' + + +========================= +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 |