cairo/CODING_STYLE

   1 Cairo coding style.
   2
   3 This document is intended to be a short description of the preferred
   4 coding style for the cairo source code. Good style requires good
   5 taste, which means this can't all be reduced to automated rules, and
   6 there are exceptions.
   7
   8 We want the code to be easy to understand and maintain, and consistent
   9 style plays an important part in that, even if some of the specific
  10 details seem trivial. If nothing else, this document gives a place to
  11 put consistent answers for issues that would otherwise be arbitrary.
  12
  13 Most of the guidelines here are demonstrated by examples, (which means
  14 this document is quicker to read than it might appear given its
  15 length). Most of the examples are positive examples that you should
  16 imitate. The few negative examples are clearly marked with a comment
  17 of /* Yuck! */. Please don't submit code to cairo that looks like any
  18 of these.
  19
  20 Indentation
  21 -----------
  22 Each new level is indented 4 more spaces than the previous level:
  23
  24         if (condition)
  25             do_something ();
  26
  27 This may be achieved with space characters or a combination of tab
  28 characters and space characters. It may not be achieved with tab
  29 characters exclusively (see below).
  30
  31 Tab characters
  32 --------------
  33 The tab character must always be interpreted according to its
  34 traditional meaning:
  35
  36         Advance to the next column which is a multiple of 8.
  37
  38 With this definition, even levels of indentation can be achieved with
  39 a sequence of tab characters, while odd levels of indentation may
  40 begin with a sequence of tab character but must end with 4 space
  41 characters.
  42
  43 Some programmers have been misled by certain text editors into
  44 thinking that 4-space indentation can be achieved with tab characters
  45 exclusively by changing the meaning of tab character to be "advance to
  46 the next column which is a multiple of 4". Code formatted in this way,
  47 making an assumption of a fictitious 4-character-tab will not be
  48 accepted into cairo.
  49
  50 The rationale here is that tabs are used in the code for lining things
  51 up other than indentation, (see the Whitespace section below), and
  52 changing the interpretation of tab from its traditional meaning will
  53 break this alignment.
  54
  55 Braces
  56 ------
  57 Most 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
  66 but 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
  78 and that seems just fine. We won't lay down any strict rule on this
  79 point, (though there should be some local consistency). If you came
  80 here hoping to find some guidance, then use the first form above.
  81
  82 If all of the substatements of an if statement are single statements,
  83 the optional braces should not usually appear:
  84
  85         if (condition)
  86             do_this ();
  87         else
  88             do_that ();
  89
  90 But the braces are mandatory when mixing single statement and compound
  91 statements 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
  99 And of course, there are exceptions for when the code just looks
 100 better 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
 114 And note that this last example also shows a situation in which the
 115 opening 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
 123 As we said above, legible code that is easy to understand and maintain
 124 is the goal, not adherence to strict rules.
 125
 126 Whitespace
 127 ----------
 128 Separate logically distinct chunks with a single newline. This
 129 obviously applies between functions, but also applies within a
 130 function or block and can even be used to good effect within a
 131 structure 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
 153 Use a single space before a left parenthesis, except where the
 154 standard will not allow it, (eg. when defining a parameterized macro).
 155
 156 Don't eliminate newlines just because things would still fit on one
 157 line. This breaks the expected visual structure of the code making it
 158 much harder to read and understand:
 159
 160         if (condition) foo (); else bar ();     /* Yuck! */
 161
 162 Do eliminate trailing whitespace (space or tab characters) on any
 163 line. Also, avoid putting initial or final blank lines into any file,
 164 and never use multiple blank lines instead of a single blank line.
 165
 166 Do enable the default git pre-commit hook that detect trailing
 167 whitespace for you and help you to avoid corrupting cairo's tree with
 168 it. Do that as follows:
 169
 170         chmod a+x .git/hooks/pre-commit
 171
 172 You might also find the git-stripspace utility helpful which acts as a
 173 filter to remove trailing whitespace as well as initial, final, and
 174 duplicate blank lines.
 175
 176 As a special case of the bracing and whitespace guidelines, function
 177 definitions should always take the following form:
 178
 179         void
 180         my_function (argument)
 181         {
 182             do_my_things ();
 183         }
 184
 185 And function prototypes should similarly have the return type (and
 186 associated specifiers and qualifiers) on a line above the function, so
 187 that the function name is flush left.
 188
 189 Break up long lines (> ~80 characters) and use whitespace to align
 190 things nicely. For example the arguments in a long list to a function
 191 call should all be aligned with each other:
 192
 193         align_function_arguments (argument_the_first,
 194                                   argument_the_second,
 195                                   argument_the_third);
 196
 197 And as a special rule, in a function prototype, (as well as in the
 198 definition), whitespace should be inserted between the parameter types
 199 and 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
 207 Note that parameters with a * prefix are aligned one character to the
 208 left so that the actual names are aligned.
 209
 210 Managing nested blocks
 211 ----------------------
 212 Long blocks that are deeply nested make the code very hard to
 213 read. Fortunately such blocks often indicate logically distinct chunks
 214 of functionality that are begging to be split into their own
 215 functions. Please listen to the blocks when they beg.
 216
 217 In other cases, gratuitous nesting comes about because the primary
 218 functionality gets buried in a nested block rather than living at the
 219 primary 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
 230 This kind of gratuitous nesting can be avoided by following a pattern
 231 of 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
 242 The return statement is often the best thing to use in a pattern like
 243 this. If it's not available due to additional nesting above which
 244 require some cleanup after the current block, then consider splitting
 245 the current block into a new function before using goto.
 246
 247 Memory allocation
 248 -----------------
 249
 250 Because much of cairo's data consists of dynamically allocated arrays,
 251 it's very easy to introduce integer overflow issues whenever malloc()
 252 is called.  Use the _cairo_malloc2(), _cairo_malloc3(), and
 253 _cairo_malloc2_add1 macros to avoid these cases; these macros check
 254 for 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
 268 In general, be wary of performing any arithmetic operations in an
 269 argument to malloc.  You should explicitly check for integer overflow
 270 yourself in any more complex situations.
 271
 272 Mode lines
 273 ----------
 274
 275 So given the rules above, what is the best way to simplify one's life as
 276 a code monkey? Get your editor to do most of the tedious work of
 277 beautifying your code!
 278
 279 As a reward for reading this far, here are some mode lines for the more
 280 popular 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
 287 TODO
 288 ----
 289
 290 Write rules for common editors to use this style.  Also cleanup/unify
 291 the modelines in the source files.