Cairo coding style. This document is intended to be a short description of the preferred coding style for the cairo source code. Good style requires good taste, which means this can't all be reduced to automated rules, and there are exceptions. We want the code to be easy to understand and maintain, and consistent style plays an important part in that, even if some of the specific details seem trivial. If nothing else, this document gives a place to put consistent answers for issues that would otherwise be arbitrary. Most of the guidelines here are demonstrated by examples, (which means this document is quicker to read than it might appear given its length). Most of the examples are positive examples that you should imitate. The few negative examples are clearly marked with a comment of /* Yuck! */. Please don't submit code to cairo that looks like any of these. Indentation ----------- Each new level is indented 4 more spaces than the previous level: if (condition) do_something (); This may be achieved with space characters or a combination of tab characters and space characters. It may not be achieved with tab characters exclusively (see below). Tab characters -------------- The tab character must always be interepreted according to its traditional meaning: Advance to the next column which is a multiple of 8. With this definition, even levels of indentation can be achieved with a sequence of tab characters, while odd levels of indentation may begin with a sequence of tab character but must end with 4 space characters. Some programmers have been misled by certain text editors into thinking that 4-space indentation can be achieved with tab characters exclusively by changing the meaning of tab character to be "advance to the next column which is a multiple of 4". Code formatted in this way, making an assumption of a fictitious 4-character-tab will not be accepted into cairo. The rationale here is that tabs are used in the code for lining things up other than indentation, (see the Whitespace section below), and changing the interpretation of tab from its traditional meaning will break this alignment. Braces ------ Most of the code in cairo uses bracing in the style of K&R: if (condition) { do_this (); do_that (); } else { do_the_other (); } but some of the code uses an alternate style: if (condition) { do_this (); do_that (); } else { do_the_other (); } and that seems just fine. We won't lay down any strict rule on this point, (though there should be some local consistency). If you came here hoping to find some guidance, then use the first form above. If all of the substatements of an if statement are single statements, the optional braces should not usually appear: if (condition) do_this (); else do_that (); But the braces are mandatory when mixing single statement and compound statements in the various clauses. For example, do not do this: if (condition) { do_this (); do_that (); } else /* Yuck! */ do_the_other (); And of course, there are exceptions for when the code just looks better with the braces: if (condition) { /* Note that we have to be careful here. */ do_something_dangerous (with_care); } if (condition && other_condition && yet_another) { do_something (); } And note that this last example also shows a situation in which the opening brace really needs to be on its own line. The following looks awful: if (condition && other_condition && yet_another) { /* Yuck! */ do_something (); } As we said above, legible code that is easy to understand and maintain is the goal, not adherence to strict rules. Whitespace ---------- Separate logically distinct chunks with a single newline. This obviously applies between functions, but also applies within a function or block and can even be used to good effect within a structure definition: struct _cairo_gstate { cairo_operator_t op; double tolerance; /* stroke style */ double line_width; cairo_line_cap_t line_cap; cairo_line_join_t line_join; double miter_limit; cairo_fill_rule_t fill_rule; double *dash; int num_dashes; double dash_offset; ... } Use a single space before a left parenthesis, except where the standard will not allow it, (eg. when defining a parameterized macro). Don't eliminate whitespace just because things would still fit on one line. This breaks the expected visual structure of the code making it much harder to read and understand: if (condition) foo (); else bar (); /* Yuck! */ As a special case of the bracing and whitespace guidelines, function definitions should always take the following form: void my_function (argument) { do_my_things (); } And function prototypes should similarly have the return type (and associated specifiers and qualifiers) on a line above the function, so that the function name is flush left. Break up long lines (> ~80 characters) and use whitespace to align things nicely. For example the arguments in a long list to a function call should all be aligned with each other: align_function_arguments (argument_the_first, argument_the_second, argument_the_third); And as a special rule, in a function prototype, (as well as in the definition), whitespace should be inserted between the parameter types and names so that the names are aligned: void align_parameter_names_in_prototypes (const char *char_star_arg, int int_arg, double *double_star_arg, double double_arg); Note that parameters with a * prefix are aligned one character to the left so that the actual names are aligned. Managing nested blocks ---------------------- Long blocks that are deeply nested make the code very hard to read. Fortunately such blocks often indicate logically distinct chunks of functionality that are begging to be split into their own functions. Please listen to the blocks when they beg. In other cases, gratuitous nesting comes about because the primary functionality gets buried in a nested block rather than living at the primary level where it belongs. Consider the following: foo = malloc (sizeof (foo_t)); if (foo) { /* Yuck! */ ... /* lots of code to initialize foo */ ... return SUCCESS; } return FAILURE; This kind of gratuitous nesting can be avoided by following a pattern of handling exceptional cases early and returning: foo = malloc (sizeof (foo_t)); if (foo == NULL) return FAILURE; ... /* lots of code to initialize foo */ ... return SUCCESS; The return statement is often the best thing to use in a pattern like this. If it's not available due to additional nesting above which require some cleanup after the current block, then consider splitting the current block into a new function before using goto.