← Back to branch summary

~zulcss/samba/server-dailies-3.4

« back to all changes in this revision

Viewing changes to README.Coding

  • Committer: Chuck Short
  • Date: 2010-09-28 20:38:39 UTC
  • Revision ID: zulcss@ubuntu.com-20100928203839-pgjulytsi9ue63x1
Initial version

Show diffs side-by-side

added added

removed removed

Lines of Context:
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