1Cairo coding style. 2 3This document is intended to be a short description of the preferred 4coding style for the cairo source code. Good style requires good 5taste, which means this can't all be reduced to automated rules, and 6there are exceptions. 7 8We want the code to be easy to understand and maintain, and consistent 9style plays an important part in that, even if some of the specific 10details seem trivial. If nothing else, this document gives a place to 11put consistent answers for issues that would otherwise be arbitrary. 12 13Most of the guidelines here are demonstrated by examples, (which means 14this document is quicker to read than it might appear given its 15length). Most of the examples are positive examples that you should 16imitate. The few negative examples are clearly marked with a comment 17of /* Yuck! */. Please don't submit code to cairo that looks like any 18of these. 19 20Indentation 21----------- 22Each new level is indented 4 more spaces than the previous level: 23 24 if (condition) 25 do_something (); 26 27This may be achieved with space characters or a combination of tab 28characters and space characters. It may not be achieved with tab 29characters exclusively (see below). 30 31Tab characters 32-------------- 33The tab character must always be interpreted according to its 34traditional meaning: 35 36 Advance to the next column which is a multiple of 8. 37 38With this definition, even levels of indentation can be achieved with 39a sequence of tab characters, while odd levels of indentation may 40begin with a sequence of tab character but must end with 4 space 41characters. 42 43Some programmers have been misled by certain text editors into 44thinking that 4-space indentation can be achieved with tab characters 45exclusively by changing the meaning of tab character to be "advance to 46the next column which is a multiple of 4". Code formatted in this way, 47making an assumption of a fictitious 4-character-tab will not be 48accepted into cairo. 49 50The rationale here is that tabs are used in the code for lining things 51up other than indentation, (see the Whitespace section below), and 52changing the interpretation of tab from its traditional meaning will 53break this alignment. 54 55Braces 56------ 57Most of the code in cairo uses bracing in the style of K&R: 58 59 if (condition) { 60 do_this (); 61 do_that (); 62 } else { 63 do_the_other (); 64 } 65 66but some of the code uses an alternate style: 67 68 if (condition) 69 { 70 do_this (); 71 do_that (); 72 } 73 else 74 { 75 do_the_other (); 76 } 77 78and that seems just fine. We won't lay down any strict rule on this 79point, (though there should be some local consistency). If you came 80here hoping to find some guidance, then use the first form above. 81 82If all of the substatements of an if statement are single statements, 83the optional braces should not usually appear: 84 85 if (condition) 86 do_this (); 87 else 88 do_that (); 89 90But the braces are mandatory when mixing single statement and compound 91statements in the various clauses. For example, do not do this: 92 93 if (condition) { 94 do_this (); 95 do_that (); 96 } else /* Yuck! */ 97 do_the_other (); 98 99And of course, there are exceptions for when the code just looks 100better with the braces: 101 102 if (condition) { 103 /* Note that we have to be careful here. */ 104 do_something_dangerous (with_care); 105 } 106 107 if (condition && 108 other_condition && 109 yet_another) 110 { 111 do_something (); 112 } 113 114And note that this last example also shows a situation in which the 115opening brace really needs to be on its own line. The following looks awful: 116 117 if (condition && 118 other_condition && 119 yet_another) { /* Yuck! */ 120 do_something (); 121 } 122 123As we said above, legible code that is easy to understand and maintain 124is the goal, not adherence to strict rules. 125 126Whitespace 127---------- 128Separate logically distinct chunks with a single newline. This 129obviously applies between functions, but also applies within a 130function or block and can even be used to good effect within a 131structure definition: 132 133 struct _cairo_gstate { 134 cairo_operator_t op; 135 136 double tolerance; 137 138 /* stroke style */ 139 double line_width; 140 cairo_line_cap_t line_cap; 141 cairo_line_join_t line_join; 142 double miter_limit; 143 144 cairo_fill_rule_t fill_rule; 145 146 double *dash; 147 int num_dashes; 148 double dash_offset; 149 150 ... 151 } 152 153Use a single space before a left parenthesis, except where the 154standard will not allow it, (eg. when defining a parameterized macro). 155 156Don't eliminate newlines just because things would still fit on one 157line. This breaks the expected visual structure of the code making it 158much harder to read and understand: 159 160 if (condition) foo (); else bar (); /* Yuck! */ 161 162Do eliminate trailing whitespace (space or tab characters) on any 163line. Also, avoid putting initial or final blank lines into any file, 164and never use multiple blank lines instead of a single blank line. 165 166Do enable the default git pre-commit hook that detect trailing 167whitespace for you and help you to avoid corrupting cairo's tree with 168it. Do that as follows: 169 170 chmod a+x .git/hooks/pre-commit 171 172You might also find the git-stripspace utility helpful which acts as a 173filter to remove trailing whitespace as well as initial, final, and 174duplicate blank lines. 175 176As a special case of the bracing and whitespace guidelines, function 177definitions should always take the following form: 178 179 void 180 my_function (argument) 181 { 182 do_my_things (); 183 } 184 185And function prototypes should similarly have the return type (and 186associated specifiers and qualifiers) on a line above the function, so 187that the function name is flush left. 188 189Break up long lines (> ~80 characters) and use whitespace to align 190things nicely. For example the arguments in a long list to a function 191call should all be aligned with each other: 192 193 align_function_arguments (argument_the_first, 194 argument_the_second, 195 argument_the_third); 196 197And as a special rule, in a function prototype, (as well as in the 198definition), whitespace should be inserted between the parameter types 199and names so that the names are aligned: 200 201 void 202 align_parameter_names_in_prototypes (const char *char_star_arg, 203 int int_arg, 204 double *double_star_arg, 205 double double_arg); 206 207Note that parameters with a * prefix are aligned one character to the 208left so that the actual names are aligned. 209 210Managing nested blocks 211---------------------- 212Long blocks that are deeply nested make the code very hard to 213read. Fortunately such blocks often indicate logically distinct chunks 214of functionality that are begging to be split into their own 215functions. Please listen to the blocks when they beg. 216 217In other cases, gratuitous nesting comes about because the primary 218functionality gets buried in a nested block rather than living at the 219primary level where it belongs. Consider the following: 220 221 foo = malloc (sizeof (foo_t)); 222 if (foo) { /* Yuck! */ 223 ... 224 /* lots of code to initialize foo */ 225 ... 226 return SUCCESS; 227 } 228 return FAILURE; 229 230This kind of gratuitous nesting can be avoided by following a pattern 231of handling exceptional cases early and returning: 232 233 foo = malloc (sizeof (foo_t)); 234 if (foo == NULL) 235 return FAILURE; 236 237 ... 238 /* lots of code to initialize foo */ 239 ... 240 return SUCCESS; 241 242The return statement is often the best thing to use in a pattern like 243this. If it's not available due to additional nesting above which 244require some cleanup after the current block, then consider splitting 245the current block into a new function before using goto. 246 247Memory allocation 248----------------- 249 250Because much of cairo's data consists of dynamically allocated arrays, 251it's very easy to introduce integer overflow issues whenever malloc() 252is called. Use the _cairo_malloc2(), _cairo_malloc3(), and 253_cairo_malloc2_add1 macros to avoid these cases; these macros check 254for overflow and will return NULL in that case. 255 256 malloc (n * size) => _cairo_malloc_ab (n, size) 257 e.g. malloc (num_elts * sizeof(some_type)) => 258 _cairo_malloc2 (num_elts, sizeof(some_type)) 259 260 malloc (a * b * size) => _cairo_malloc_abc (a, b, size) 261 e.g. malloc (width * height * 4) => 262 _cairo_malloc3 (width, height, 4) 263 264 malloc (n * size + k) => _cairo_malloc_ab_plus_c (n, size, k) 265 e.g. malloc (num * sizeof(entry) + sizeof(header)) => 266 _cairo_malloc2k (num, sizeof(entry), sizeof(header)) 267 268In general, be wary of performing any arithmetic operations in an 269argument to malloc. You should explicitly check for integer overflow 270yourself in any more complex situations. 271 272Mode lines 273---------- 274 275So given the rules above, what is the best way to simplify one's life as 276a code monkey? Get your editor to do most of the tedious work of 277beautifying your code! 278 279As a reward for reading this far, here are some mode lines for the more 280popular editors: 281/* 282 * vim:sw=4:sts=4:ts=8:tw=78:fo=tcroq:cindent:cino=\:0,(0 283 * vim:isk=a-z,A-Z,48-57,_,.,-,> 284 */ 285 286 287TODO 288---- 289 290Write rules for common editors to use this style. Also cleanup/unify 291the modelines in the source files. 292