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