Home | History | Annotate | Line # | Download | only in dist 
      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 
    200