ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/svn/vendor/ircservices-5.1.24/docs/tech/d.html
Revision: 3389
Committed: Fri Apr 25 14:12:15 2014 UTC (9 years, 10 months ago) by michael
Content type: text/html
File size: 12957 byte(s)
Log Message:
- Imported ircservices-5.1.24

File Contents

# Content
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>-&gt;</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-&gt;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-&gt;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-&gt;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>