| 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. |