diff options
Diffstat (limited to 'libs/cairo-1.16.0/CODING_STYLE')
| -rw-r--r-- | libs/cairo-1.16.0/CODING_STYLE | 291 |
1 files changed, 0 insertions, 291 deletions
diff --git a/libs/cairo-1.16.0/CODING_STYLE b/libs/cairo-1.16.0/CODING_STYLE deleted file mode 100644 index 95ceac0..0000000 --- a/libs/cairo-1.16.0/CODING_STYLE +++ /dev/null @@ -1,291 +0,0 @@ -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 interpreted 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 newlines 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! */ - -Do eliminate trailing whitespace (space or tab characters) on any -line. Also, avoid putting initial or final blank lines into any file, -and never use multiple blank lines instead of a single blank line. - -Do enable the default git pre-commit hook that detect trailing -whitespace for you and help you to avoid corrupting cairo's tree with -it. Do that as follows: - - chmod a+x .git/hooks/pre-commit - -You might also find the git-stripspace utility helpful which acts as a -filter to remove trailing whitespace as well as initial, final, and -duplicate blank lines. - -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. - -Memory allocation ------------------ - -Because much of cairo's data consists of dynamically allocated arrays, -it's very easy to introduce integer overflow issues whenever malloc() -is called. Use the _cairo_malloc2(), _cairo_malloc3(), and -_cairo_malloc2_add1 macros to avoid these cases; these macros check -for overflow and will return NULL in that case. - - malloc (n * size) => _cairo_malloc_ab (n, size) - e.g. malloc (num_elts * sizeof(some_type)) => - _cairo_malloc2 (num_elts, sizeof(some_type)) - - malloc (a * b * size) => _cairo_malloc_abc (a, b, size) - e.g. malloc (width * height * 4) => - _cairo_malloc3 (width, height, 4) - - malloc (n * size + k) => _cairo_malloc_ab_plus_c (n, size, k) - e.g. malloc (num * sizeof(entry) + sizeof(header)) => - _cairo_malloc2k (num, sizeof(entry), sizeof(header)) - -In general, be wary of performing any arithmetic operations in an -argument to malloc. You should explicitly check for integer overflow -yourself in any more complex situations. - -Mode lines ----------- - -So given the rules above, what is the best way to simplify one's life as -a code monkey? Get your editor to do most of the tedious work of -beautifying your code! - -As a reward for reading this far, here are some mode lines for the more -popular editors: -/* - * vim:sw=4:sts=4:ts=8:tw=78:fo=tcroq:cindent:cino=\:0,(0 - * vim:isk=a-z,A-Z,48-57,_,.,-,> - */ - - -TODO ----- - -Write rules for common editors to use this style. Also cleanup/unify -the modelines in the source files. |