1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11-strict.dtd"> |
3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
4 |
<head> |
5 |
<meta http-equiv="Content-Style-Type" content="text/css"/> |
6 |
<style type="text/css">@import "style.css";</style> |
7 |
<title>IRC Services Technical Reference Manual - Appendix D. Coding style guidelines</title> |
8 |
</head> |
9 |
|
10 |
<body> |
11 |
<h1 class="title" id="top">IRC Services Technical Reference Manual</h1> |
12 |
|
13 |
<h2 class="section-title">Appendix D. Coding style guidelines</h2> |
14 |
|
15 |
<p class="section-toc"> |
16 |
D-1. <a href="#s1">Formatting</a> |
17 |
<br/>D-2. <a href="#s2">Identifier naming</a> |
18 |
</p> |
19 |
|
20 |
<p class="backlink"><a href="index.html">Table of Contents</a></p> |
21 |
|
22 |
<!------------------------------------------------------------------------> |
23 |
<hr/> |
24 |
|
25 |
<p>The following guidelines were observed when writing the Services source |
26 |
code. Note, however, that they were treated as guidelines, not rules, with |
27 |
the cardinal rule being "readability first".</p> |
28 |
|
29 |
<!------------------------------------------------------------------------> |
30 |
<hr/> |
31 |
|
32 |
<h3 class="subsection-title" id="s1">D-1. Formatting</h3> |
33 |
|
34 |
<ul> |
35 |
<li class="spaced">Lines must not be longer than 79 columns.</li> |
36 |
|
37 |
<li class="spaced">The basic indentation unit is four columns.</li> |
38 |
|
39 |
<li class="spaced">Tab (ASCII <tt>\011</tt>) characters are not permitted |
40 |
in source files; indents should always be done using using spaces |
41 |
(<tt>\040</tt>). The source files distributed with Services |
42 |
include settings for the Emacs and Vim editors that cause the Tab |
43 |
key to insert spaces rather than a tab character.</li> |
44 |
|
45 |
<li class="spaced">Only one statement is allowed per line. Statements |
46 |
(including the empty statement "<tt>;</tt>") may not be written on |
47 |
the same line as a control keyword (<tt>if</tt>, <tt>for</tt>, or |
48 |
<tt>while</tt>).</li> |
49 |
|
50 |
<li class="spaced">Spaces are placed between binary operators and their |
51 |
operands, except for the member-reference operators "<tt>-></tt>" |
52 |
and "<tt>.</tt>"; spaces are not placed between unary operators and |
53 |
their operands. However, spaces may be omitted around binary |
54 |
operators when it would improve readability. Examples: |
55 |
|
56 |
<div class="code">i = j * 2; |
57 |
user->channelcount++; |
58 |
result += i*60 + (j+59)/60;</div></li> |
59 |
|
60 |
<li class="spaced"><tt>NULL</tt>, not <tt>0</tt>, should always be used in |
61 |
pointer comparisons. For character comparisons, <tt>0</tt> is |
62 |
preferred to <tt>'\0'</tt>, but the latter may also be used if it |
63 |
does not go against the style of the surrounding code. Do not use |
64 |
<tt>'\0'</tt> with variables declared as type <tt>int8</tt> or |
65 |
<tt>uint8</tt>, even though these types are usually equivalent to |
66 |
<tt>char</tt> and <tt>unsigned char</tt>.</li> |
67 |
|
68 |
<li class="spaced">The construct "<tt>!!<i>expression</i></tt>" should not |
69 |
be used. Use "<tt><i>expression</i> != 0</tt>" (for characters or |
70 |
integers) or "<tt><i>expression</i> != NULL</tt>" (for pointers) |
71 |
instead.</li> |
72 |
|
73 |
<li class="spaced">Parentheses are required when <tt>&&</tt> and |
74 |
<tt>||</tt> are used in the same expression to explicitly indicate |
75 |
order of evaluation; do not rely on the default order of evaluation. |
76 |
(Not using parentheses will generate a warning when using <tt>gcc |
77 |
-Wall</tt>.)</li> |
78 |
|
79 |
<li class="spaced">Parentheses following the control statements "<tt>if</tt>", |
80 |
"<tt>for</tt>", and "<tt>while</tt>", as well as the macros |
81 |
<tt>LIST_FOREACH</tt>, <tt>LIST_FOREACH_SAFE</tt>, and |
82 |
<tt>ARRAY_FOREACH</tt>, are preceded by a space. Parentheses |
83 |
following function or macro calls (other than the above) are not |
84 |
preceded by a space. Example: |
85 |
|
86 |
<div class="code">if (flag) |
87 |
function();</div></li> |
88 |
|
89 |
<li class="spaced">Spaces are placed after the comma of each parameter to a |
90 |
function or macro; however, they may be omitted in function calls |
91 |
which are themselves parameters to a function or macro, or when |
92 |
including them would make the line exceed the length limit. Spaces |
93 |
are also placed after (but not before) the semicolons in a |
94 |
<tt>for</tt> statement. Spaces are not placed after the opening |
95 |
parenthesis or before the closing parenthesis of a function/macro |
96 |
call or control statement. Examples: |
97 |
|
98 |
<div class="code">function(param1, param2); |
99 |
function(param1, strchr(string,'/'), param3); |
100 |
for (i = 0; i < count; i++) ...</div></li> |
101 |
|
102 |
<li class="spaced">Opening braces of control statement blocks go on the |
103 |
same line as the control statement (<tt>if</tt>, <tt>for</tt>, |
104 |
etc.) associated with the block; function blocks and "naked blocks" |
105 |
(those not associated with any control statement or function) have |
106 |
the opening brace alone on a line, indented to the same level as |
107 |
the surrounding code. Closing braces are indented to the same |
108 |
level as the line containing the opening brace. Examples: |
109 |
|
110 |
<div class="code">if (flag) { |
111 |
/* indented code goes here */ |
112 |
... |
113 |
} |
114 |
|
115 |
int function(int param1, char *param2) |
116 |
{ |
117 |
/* indented code goes here */ |
118 |
... |
119 |
/* start of a naked block */ |
120 |
{ |
121 |
int foo; |
122 |
... |
123 |
} |
124 |
}</div></li> |
125 |
|
126 |
<li class="spaced">If an <tt>if</tt> statement is longer than one line, it |
127 |
should be broken at logical operators (<tt>&&</tt> or <tt>||</tt>); |
128 |
the operator should be placed at the beginning of the next line, |
129 |
and should be indented to show which term the operator belongs |
130 |
with. The closing parenthesis for the <tt>if</tt> statement and |
131 |
the subsequent open brace should be alone on a line, aligned with |
132 |
the first line of the <tt>if</tt> statement. (Braces are required |
133 |
in this case.) Conditions for <tt>for</tt> and <tt>while</tt> |
134 |
statements should never span multiple lines, though a <tt>for</tt> |
135 |
statement may be broken at the semicolons if necessary. Examples: |
136 |
|
137 |
<div class="code">if (ok && (strcmp(option, "option-name-1") == 0 |
138 |
|| strcmp(option, "option-name-2") == 0) |
139 |
) { |
140 |
... |
141 |
} |
142 |
|
143 |
if (!init_first() |
144 |
|| !init_second() |
145 |
|| !init_third() |
146 |
|| !init_fourth() |
147 |
) { |
148 |
/* This example outdents the || by three spaces to line |
149 |
* up the terms. Such outdenting is acceptable if it |
150 |
* makes the code easier to read and understand. */ |
151 |
... |
152 |
} |
153 |
|
154 |
for (exception = first_maskdata(MD_EXCEPTION); exception != NULL; |
155 |
exception = next_maskdata(MD_EXCEPTION) |
156 |
) { |
157 |
... |
158 |
}</div></li> |
159 |
|
160 |
<li class="spaced">An <tt>else</tt> followed by an <tt>if</tt> is considered to be a |
161 |
single keyword, "<tt>else if</tt>". The <tt>if</tt> part should |
162 |
always be placed on the same line as and immediately following the |
163 |
<tt>else</tt>; the <tt>else if</tt> should never be split up onto |
164 |
two lines, nor should braces be used around the <tt>if</tt> block. |
165 |
The exception to this is when the <tt>else</tt> and <tt>if</tt> |
166 |
refer to two conceptually distinct sets of conditions, in which |
167 |
case the <tt>if</tt> block should be enclosed by braces and |
168 |
indented. Example: |
169 |
|
170 |
<div class="code">res = check_password( /* ... */ ); |
171 |
if (res == 0) { |
172 |
... |
173 |
} else if (res == 1) { |
174 |
/* "else if" on a single line */ |
175 |
... |
176 |
} else { |
177 |
if (user->ni != NULL) { |
178 |
/* "if" condition is different from "else" |
179 |
* condition, thus separate */ |
180 |
... |
181 |
} |
182 |
}</div></li> |
183 |
|
184 |
<li class="spaced">Braces are always placed around the body of a control statement |
185 |
(<tt>if</tt>, <tt>for</tt>, etc.). The two exceptions are |
186 |
<tt>else</tt> followed by <tt>if</tt>, mentioned above, and |
187 |
statements for which the body, as well as the bodies of any |
188 |
<tt>else if</tt> or <tt>else</tt> statements for an <tt>if</tt> |
189 |
statement, are all one statement in length and do not contain any |
190 |
nested control statements; in this latter case, braces are optional |
191 |
(but recommended if any of the statements span multiple lines). |
192 |
Examples: |
193 |
|
194 |
<div class="code">for (i = 0; i < count; i++) |
195 |
function(i); |
196 |
|
197 |
while (!done) { |
198 |
/* Braces required because of the nested "if" */ |
199 |
if (do_stuff()) |
200 |
done = 1; |
201 |
} |
202 |
|
203 |
if (state == 0) { |
204 |
a = b; |
205 |
} else if (state == 1) { |
206 |
/* Every if/else body gets braces because this body |
207 |
* has two statements */ |
208 |
b += a; |
209 |
a = 0; |
210 |
} else { |
211 |
state = 0; |
212 |
}</div></li> |
213 |
|
214 |
<li class="spaced">When using multiply-nested control statements, or a single control |
215 |
statement which has a long block, the closing brace of the block |
216 |
should be followed by a comment indicating what control statement |
217 |
the block belongs to. This should usually be the content of the |
218 |
control statement, but may be abbreviated as long as its meaning is |
219 |
clear. If a long <tt>if</tt> block is followed by an <tt>else</tt> |
220 |
clause, the <tt>else</tt> should likewise be documented. Examples: |
221 |
|
222 |
<div class="code">while (i < count) { |
223 |
... |
224 |
} /* while (i < count) */ |
225 |
|
226 |
if (flag) { |
227 |
... |
228 |
} else { /* !flag */ |
229 |
... |
230 |
} /* if (flag) */ |
231 |
|
232 |
for (node = first; node != NULL; node = node->next) { |
233 |
... |
234 |
} /* for all nodes */</div></li> |
235 |
|
236 |
<li class="spaced"><tt>case</tt> and <tt>default</tt> labels for a <tt>switch</tt> |
237 |
should be indented half of a normal indentation unit (two columns) |
238 |
from the line containing the <tt>switch</tt> with which they are |
239 |
associated; statements associated with a case should be indented a |
240 |
full unit from the line containing the <tt>switch</tt> (half a unit |
241 |
from the <tt>case</tt>). If a case requires its own block, such as |
242 |
when it declares its own local variables, the opening brace is |
243 |
placed after the colon on the <tt>case</tt> line. Example: |
244 |
|
245 |
<div class="code">switch (variable) { |
246 |
case 123: { |
247 |
int foo; |
248 |
... |
249 |
break; |
250 |
} /* case 123 */ |
251 |
default: |
252 |
... |
253 |
return -1; |
254 |
}</div></li> |
255 |
|
256 |
<li class="spaced">When a case in a <tt>switch</tt> block does not contain a |
257 |
<tt>break</tt> (or <tt>return</tt>) statement and deliberately |
258 |
"falls through" to the next case, a comment to this effect should |
259 |
be made at the bottom of the case. Example: |
260 |
|
261 |
<div class="code">switch (state) { |
262 |
case 0: |
263 |
... |
264 |
/* fall through */ |
265 |
case 1: |
266 |
... |
267 |
break; |
268 |
}</div></li> |
269 |
|
270 |
<li class="spaced">Inline comments (comments placed to the right of a line of code) |
271 |
should be aligned to start on the same column, when this does not |
272 |
place too much space between the comment and the code or cause the |
273 |
line to exceed 79 columns in length. Inline comments after |
274 |
unusually long lines (such as long field declarations in |
275 |
structures) should be placed alone on the following line, indented |
276 |
the proper amount.</li> |
277 |
|
278 |
<li class="spaced">The <tt>goto</tt> statement should not be used except in error |
279 |
handling situations where it will help avoid multiple levels of |
280 |
<tt>if</tt> nesting or other awkward code. Labels for |
281 |
<tt>goto</tt> should be outdented half of an indentation unit |
282 |
from the surrounding code (<i>i.e.</i>, indented two columns less |
283 |
than the surrounding code).</li> |
284 |
</ul> |
285 |
|
286 |
<p class="backlink"><a href="#top">Back to top</a></p> |
287 |
|
288 |
<!------------------------------------------------------------------------> |
289 |
<hr/> |
290 |
|
291 |
<h3 class="subsection-title" id="s2">D-2. Identifier naming</h3> |
292 |
|
293 |
<ul> |
294 |
<li class="spaced">Global variables and type names should use mixed upper- and |
295 |
lower-case, with an upper-case letter at the beginning of each |
296 |
distinct word in the name.</li> |
297 |
|
298 |
<li class="spaced">Preprocessor constants and macros should use all upper-case |
299 |
letters, with an underscore between distinct words in the |
300 |
name.</li> |
301 |
|
302 |
<li class="spaced">Structure names and local variables should use all lower-case |
303 |
letters, with an underscore between distinct words in the |
304 |
name.</li> |
305 |
|
306 |
<li class="spaced">Structure names for structures with an associated type name |
307 |
(<i>i.e.</i>, from <tt>typedef</tt>) should be given the same name |
308 |
as the type, except with all letters in lowercase and followed by |
309 |
an underscore. Example: |
310 |
|
311 |
<div class="code">typedef struct mytype_ MyType; |
312 |
struct mytype_ { |
313 |
MyType *next, *prev; |
314 |
... |
315 |
};</div></li> |
316 |
|
317 |
<li class="spaced">Names should be descriptive. For global variables, |
318 |
preprocessor macros and constants, type names, and structure |
319 |
names, names should generally consist of one or more full words. |
320 |
For local variables, short names and abbreviations are permitted |
321 |
as long as it is clear what the variables are used for. In |
322 |
general, one-letter local variable names should not be used other |
323 |
than the following: |
324 |
<ul> |
325 |
<li><tt>c</tt>: character</li> |
326 |
<li><tt>f</tt>: file pointer (<tt>FILE *</tt>)</li> |
327 |
<li><tt>i</tt>, <tt>j</tt>, <tt>k</tt>: integers (usually |
328 |
counters)</li> |
329 |
<li><tt>n</tt>, <tt>p</tt>, <tt>q</tt>: integers (<tt>p</tt> may |
330 |
also be a pointer variable)</li> |
331 |
<li><tt>s</tt>: string</li> |
332 |
<li><tt>t</tt>: string or temporary variable</li> |
333 |
<li><tt>x</tt>, <tt>y</tt>, <tt>z</tt>: integers (usually |
334 |
position variables)</li> |
335 |
</ul> |
336 |
Two-letter variable names are often formed from initials of type |
337 |
names, such as <tt>NickInfo *ni</tt>; see the source code for |
338 |
examples.</li> |
339 |
</ul> |
340 |
|
341 |
<p class="backlink"><a href="#top">Back to top</a></p> |
342 |
|
343 |
<!------------------------------------------------------------------------> |
344 |
<hr/> |
345 |
|
346 |
<p class="backlink"><a href="index.html">Table of Contents</a></p> |
347 |
|
348 |
</body> |
349 |
</html> |