s3-build: don't rebuild/link on every make run
[ira/wip.git] / 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 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, with a few exceptions as
21 mentioned below.
22
23 But to save you the trouble of reading the Linux kernel style guide, here
24 are the highlights.
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 source3/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 source3/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 source3/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 included 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.  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 align the 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. You should always include braces, even if the block only
139 contains one statement.  NOTE: Functions are different and the beginning left
140 brace should begin on a line of its own.
141
142 If the beginning statement has to be broken across lines due to length,
143 the beginning brace should be on a line of its own.
144
145 The exception to the ending rule is when the closing brace is followed by
146 another language keyword such as else or the closing while in a do..while
147 loop.
148
149 Good examples::
150
151         if (x == 1) {
152                 printf("good\n");
153         }
154
155         for (x=1; x<10; x++) {
156                 print("%d\n", x);
157         }
158
159         for (really_really_really_really_long_var_name=0;
160              really_really_really_really_long_var_name<10;
161              really_really_really_really_long_var_name++)
162         {
163                 print("%d\n", really_really_really_really_long_var_name);
164         }
165
166         do {
167                 printf("also good\n");
168         } while (1);
169
170 Bad examples::
171
172         while (1)
173         {
174                 print("I'm in a loop!\n"); }
175
176         for (x=1;
177              x<10;
178              x++)
179         {
180                 print("no good\n");
181         }
182
183         if (i < 10)
184                 print("I should be in braces.\n");
185
186
187 Goto
188 ----
189
190 While many people have been academically taught that goto's are fundamentally
191 evil, they can greatly enhance readability and reduce memory leaks when used
192 as the single exit point from a function.  But in no Samba world what so ever 
193 is a goto outside of a function or block of code a good idea.
194
195 Good Examples::
196
197         int function foo(int y)
198         {
199                 int *z = NULL;
200                 int ret = 0;
201
202                 if (y < 10) {
203                         z = malloc(sizeof(int)*y);
204                         if (!z) {
205                                 ret = 1;
206                                 goto done;
207                         }
208                 }
209
210                 print("Allocated %d elements.\n", y);
211
212          done: 
213                 if (z)
214                         free(z);
215
216                 return ret;
217         }
218
219
220 Checking Pointer Values
221 -----------------------
222
223 When invoking functions that return pointer values, either of the following 
224 are acceptable.  Use you best judgement and choose the more readable option.
225 Remember that many other people will review it.::
226
227         if ((x = malloc(sizeof(short)*10)) == NULL ) {
228                 fprintf(stderr, "Unable to alloc memory!\n");
229         }
230
231 or::
232
233         x = malloc(sizeof(short)*10);
234         if (!x) {
235                 fprintf(stderr, "Unable to alloc memory!\n");
236         }
237
238
239 Primitive Data Types
240 --------------------
241
242 Samba has large amounts of historical code which makes use of data types 
243 commonly supported by the C99 standard. However, at the time such types 
244 as boolean and exact width integers did not exist and Samba developers 
245 were forced to provide their own.  Now that these types are guaranteed to 
246 be available either as part of the compiler C99 support or from lib/replace/, 
247 new code should adhere to the following conventions:
248
249   * Booleans are of type "bool" (not BOOL)
250   * Boolean values are "true" and "false" (not True or False)
251   * Exact width integers are of type [u]int[8|16|32|64]_t
252
253
254 Typedefs
255 --------
256
257 Samba tries to avoid "typedef struct { .. } x_t;", we always use
258 "struct x { .. };". We know there are still those typedefs in the code,
259 but for new code, please don't do that.
260
261 Make use of helper variables
262 ----------------------------
263
264 Please try to avoid passing function calls as function parameters
265 in new code. This makes the code much easier to read and
266 it's also easier to use the "step" command within gdb.
267
268 Good Example::
269
270         char *name;
271
272         name = get_some_name();
273         if (name == NULL) {
274                 ...
275         }
276
277         ret = some_function_my_name(name);
278         ...
279
280
281 Bad Example::
282
283         ret = some_function_my_name(get_some_name());
284         ...
285