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