CODING_STYLE

   1 Pixman coding style.
   2 ====================
   3
   4 The pixman coding style is close to cairo's with one exception: braces
   5 go on their own line, rather than on the line of the if/while/for:
   6
   7         if (condition)
   8         {
   9             do_something();
  10             do_something_else();
  11         }
  12
  13 not
  14
  15         if (condition) {
  16             do_something();
  17             do_something_else();
  18         }
  19
  20
  21
  22 Specific guidelines:
  23
  24
  25 Indentation
  26 ===========
  27
  28 Each new level is indented four spaces:
  29
  30         if (condition)
  31             do_something();
  32
  33 This may be achieved with space characters or with a combination of
  34 tab characters and space characters. Tab characters are interpreted as
  35
  36         Advance to the next column which is a multiple of 8.
  37
  38
  39 Names
  40 =====
  41
  42 In all names, words are separated with underscores. Do not use
  43 CamelCase for any names.
  44
  45 Macros have ALL_CAPITAL_NAMES
  46
  47 Type names are in lower case and end with "_t". For example
  48 pixman_image_t.
  49
  50 Labels, functions and variables have lower case names.
  51
  52
  53 Braces
  54 ======
  55
  56 Braces always go on their own line:
  57
  58         if (condition)
  59         {
  60             do_this ();
  61             do_that ();
  62         }
  63         else
  64         {
  65             do_the_other ();
  66         }
  67
  68 Rules for braces and substatements of if/while/for/do:
  69
  70 * If a substatement spans multiple lines, then there must be braces
  71   around it.
  72
  73 * If the condition of an if/while/for spans multiple lines, then
  74   braces must be used for the substatements.
  75
  76 * If one substatement of an if statement has braces, then the other
  77   must too.
  78
  79 * Otherwise, don't add braces.
  80
  81
  82 Comments
  83 ========
  84
  85 For comments either like this:
  86
  87         /* One line comment */
  88
  89 or like this:
  90
  91         /* This is a multi-line comment
  92          *
  93          * It extends over multiple lines
  94          */
  95
  96 Generally comments should say things that is clear from the code
  97 itself. If too many comments say obvious things, then people will just
  98 stop reading all comments, including the good ones.
  99
 100
 101 Whitespace
 102 ==========
 103
 104 * Put a single space after commas
 105
 106 * Put spaces around arithmetic operators such a +, -, *, /:
 107
 108         y * stride + x
 109
 110         x / unit_x
 111
 112 * Do not put spaces after the address-of operator, the * when used as
 113   a pointer derefernce or the ! and ~ operators:
 114
 115      &foo;
 116
 117      ~0x00000000
 118
 119      !condition
 120
 121      *result = 100
 122
 123 * Break up long lines (> ~80 characters) and use whitespace to align
 124   things nicely. This is one way:
 125
 126          some_very_long_function name (
 127                 implementation, op, src, mask, dest,
 128                 src_x, src_y, mask_x, mask_y, dest_x, dest_y,
 129                 width, height);
 130
 131   This is another:
 132
 133         some_very_long_function_name (implementation, op,
 134                                       src, mask, dest,
 135                                       src_x, src_y,
 136                                       mask_x, mask_y,
 137                                       dest_x, dest_y,
 138                                       width, height);
 139
 140 * Separate logically distinct chunks with a single newline. This
 141   obviously applies between functions, but also applies within a
 142   function or block or structure definition.
 143
 144 * Use a newline after a block of variable declarations.
 145
 146 * Use a single space before a left parenthesis, except where the
 147   standard will not allow it, (eg. when defining a parameterized macro).
 148
 149 * Don't eliminate newlines just because things would still fit on one
 150   line. This breaks the expected visual structure of the code making
 151   it much harder to read and understand:
 152
 153         if (condition) foo (); else bar ();     /* Yuck! */
 154
 155 * Do eliminate trailing whitespace (space or tab characters) on any
 156   line. Also, avoid putting initial or final blank lines into any
 157   file, and never use multiple blank lines instead of a single blank
 158   line.
 159
 160 * Do enable the default git pre-commit hook that detect trailing
 161   whitespace for you and help you to avoid corrupting cairo's tree
 162   with it. Do that as follows:
 163
 164         chmod a+x .git/hooks/pre-commit
 165
 166 * You might also find the git-stripspace utility helpful which acts as
 167   a filter to remove trailing whitespace as well as initial, final,
 168   and duplicate blank lines.
 169
 170
 171 Function Definitions
 172 ====================
 173
 174 Function definitions should take the following form:
 175
 176         void
 177         my_function (argument)
 178         {
 179             do_my_things ();
 180         }
 181
 182 If all the parameters to a function fit naturally on one line, format
 183 them that way. Otherwise, put one argument on each line, adding
 184 whitespace so that the parameter names are aligned with each other.
 185
 186 I.e., do either this:
 187
 188         void
 189         short_arguments (const char *str, int x, int y, int z)
 190         {
 191         }
 192
 193 or this:
 194
 195         void
 196         long_arguments (const char *char_star_arg,
 197                         int         int_arg,
 198                         double     *double_star_arg,
 199                         double      double_arg)
 200         {
 201         }
 202
 203
 204 Mode lines
 205 ==========
 206
 207 Given the rules above, what is the best way to simplify one's life as
 208 a code monkey? Get your editor to do most of the tedious work of
 209 beautifying your code!
 210
 211 As a reward for reading this far, here are some mode lines for the more
 212 popular editors:
 213 /*
 214  * vim:sw=4:sts=4:ts=8:tw=78:fo=tcroq:cindent:cino=\:0,(0
 215  * vim:isk=a-z,A-Z,48-57,_,.,-,>
 216  */