Debian Codegraph @

tools/xl/CODING_STYLE

raw
1 XL CODING STYLE
2 ========================
3
4
5 AN APOLOGY AND WARNING
6 ----------------------
7
8 Much of the code in xl does not yet follow this coding style
9 document in every respect. However, new code is expected to conform.
10
11 Patches to improve the style of existing code are welcome. Please
12 separate these out from functional changes.
13
14 If it is not feasible to conform fully to the style while patching old
15 code, without doing substantial style reengineering first, we may
16 accept patches which contain nonconformant elements, provided that
17 they don't make the coding style problem worse overall.
18
19 In this case, the new code should conform to the prevailing style in
20 the area being touched.
21
22 ERROR HANDLING
23 --------------
24
25 Unless, there are good reasons to do otherwise, the following error
26 handling and cleanup paradigm should be used:
27
28 * All local variables referring to resources which might need
29 cleaning up are declared at the top of the function, and
30 initialised to a sentinel value indicating "nothing allocated".
31 For example,
32 libxl_evgen_disk_eject *evg = NULL;
33 int nullfd = -1;
34
35 * If the function is to return a libxl error value, `rc' is
36 used to contain the error code, but it is NOT initialised:
37 int rc;
38
39 * There is only one error cleanup path out of the function. It
40 starts with a label `out:'. That error cleanup path checks for
41 each allocated resource and frees it iff necessary. It then
42 returns rc. For example,
43 out:
44 if (evg) libxl__evdisable_disk_eject(gc, evg);
45 if (nullfd >= 0) close(nullfd);
46 return rc;
47
48 * Function calls which might fail (ie most function calls) are
49 handled by putting the return/status value into a variable, and
50 then checking it in a separate statement:
51 char *dompath = libxl__xs_get_dompath(gc, bl->domid);
52 if (!dompath) { rc = ERROR_FAIL; goto out; }
53
54 * If a resource is freed in the main body of the function (for
55 example, in a loop), the corresponding variable has to be reset to
56 the sentinel at the point where it's freed.
57
58 Whether to use the `out' path for successful returns as well as error
59 returns is a matter of taste and convenience for the specific
60 function.
61
62 If you reuse the `out' path for successful returns, there may be
63 resources which are to be returned to the caller rather than freed.
64 In that case you have to reset the local variable to `nothing here',
65 to avoid the resource being freed on the out path. That resetting
66 should be done immediately after the resource value is stored at the
67 applicable _r function parameter (or equivalent). Do not test `rc' in
68 the out section, to discover whether to free things.
69
70 The uses of the single-line formatting in the examples above are
71 permitted exceptions to the usual xl code formatting rules.
72
73 FORMATTING AND NAMING
74 ---------------------
75
76 Blatantly copied from qemu and linux with few modifications.
77
78
79 1. Whitespace
80
81 Of course, the most important aspect in any coding style is whitespace.
82 Crusty old coders who have trouble spotting the glasses on their noses
83 can tell the difference between a tab and eight spaces from a distance
84 of approximately fifteen parsecs. Many a flamewar have been fought and
85 lost on this issue.
86
87 Xl indents are four spaces. Tabs are never used, except in
88 Makefiles where they have been irreversibly coded into the syntax.
89 Spaces of course are superior to tabs because:
90
91 - You have just one way to specify whitespace, not two. Ambiguity breeds
92 mistakes.
93 - The confusion surrounding 'use tabs to indent, spaces to justify' is gone.
94 - Tab indents push your code to the right, making your screen seriously
95 unbalanced.
96 - Tabs will be rendered incorrectly on editors who are misconfigured not
97 to use tab stops of eight positions.
98 - Tabs are rendered badly in patches, causing off-by-one errors in almost
99 every line.
100 - It is the xl coding style.
101
102 Do not leave whitespace dangling off the ends of lines.
103
104
105 2. Line width
106
107 Lines are limited to 75-80 characters.
108
109 Rationale:
110 - Some people like to tile their 24" screens with a 6x4 matrix of 80x24
111 xterms and use vi in all of them. The best way to punish them is to
112 let them keep doing it.
113 - Code and especially patches is much more readable if limited to a sane
114 line length. Eighty is traditional.
115 - It is the xl coding style.
116
117
118 3. Naming
119
120 C is a Spartan language, and so should your naming be. Unlike Modula-2
121 and Pascal programmers, C programmers do not use cute names like
122 ThisVariableIsATemporaryCounter. A C programmer would call that
123 variable "tmp", which is much easier to write, and not the least more
124 difficult to understand.
125
126 HOWEVER, while mixed-case names are frowned upon, descriptive names for
127 global variables are a must. To call a global function "foo" is a
128 shooting offense.
129
130 GLOBAL variables (to be used only if you _really_ need them) need to
131 have descriptive names, as do global functions. If you have a function
132 that counts the number of active users, you should call that
133 "count_active_users()" or similar, you should _not_ call it "cntusr()".
134
135 Encoding the type of a function into the name (so-called Hungarian
136 notation) is brain damaged - the compiler knows the types anyway and can
137 check those, and it only confuses the programmer.
138
139 LOCAL variable names should be short, and to the point. If you have
140 some random integer loop counter, it should probably be called "i".
141 Calling it "loop_counter" is non-productive, if there is no chance of it
142 being mis-understood. Similarly, "tmp" can be just about any type of
143 variable that is used to hold a temporary value.
144
145 Local variables used to store return values should have descriptive name
146 like "rc" or "ret". Following the same reasoning the label used as exit
147 path should be called "out".
148
149 Function arguments which are used to return values to the caller
150 should be suffixed `_r' or `_out'.
151
152 Variables, type names and function names are
153 lower_case_with_underscores.
154 Xl should avoid using libxl_ and libxl__ as prefix for its own function
155 names.
156
157 4. Statements
158
159 Don't put multiple statements on a single line.
160 Don't put multiple assignments on a single line either.
161 Error code paths with an if statement and a goto or a return on the same
162 line are allowed. Examples:
163
164 if (rc) goto out;
165 if (rc < 0) return;
166
167 Xl coding style is super simple. Avoid tricky expressions.
168
169
170 5. Block structure
171
172 Every indented statement is braced, but blocks that contain just one
173 statement may have the braces omitted. To avoid confusion, either all
174 the blocks in an if...else chain have braces, or none of them do.
175
176 The opening brace is on the line that contains the control flow
177 statement that introduces the new block; the closing brace is on the
178 same line as the else keyword, or on a line by itself if there is no
179 else keyword. Examples:
180
181 if (a == 5) {
182 printf("a was 5.\n");
183 } else if (a == 6) {
184 printf("a was 6.\n");
185 } else {
186 printf("a was something else entirely.\n");
187 }
188
189 if (a == 5)
190 printf("a was 5.\n");
191
192 An exception is the opening brace for a function; for reasons of tradition
193 and clarity it comes on a line by itself:
194
195 void a_function(void)
196 {
197 do_something();
198 }
199
200 Rationale: a consistent (except for functions...) bracing style reduces
201 ambiguity and avoids needless churn when lines are added or removed.
202 Furthermore, it is the xl coding style.