doc/coding_style.txt

   1 Coding Style
   2 ------------
   3
   4 This document defines coding style for GFXprim.
   5
   6 C Coding Style
   7 ~~~~~~~~~~~~~~
   8
   9 GFXprim is written in C. There is no C++ code in and I mean it. A few headers
  10 do contain '#ifndef __cplusplus' so that you can interface GFXprim headers as
  11 'extern C' without problems. If this doesn't work, let us know.
  12
  13 GFXprim follows mostly Linux Kernel coding style, see
  14 'Documentation/CodingStyle' in the Linux Kernel source or follow this
  15 link:http://www.kernel.org/doc/Documentation/CodingStyle[link] (it's funny and
  16 enligthening reading).
  17
  18 .Indentation and whitespaces
  19
  20 * We use tabs for indentation and tab is eight spaces wide.
  21
  22 * Lines should be at most 80 chars long.
  23
  24 * No additional whitespaces (other than newline) at the end of line.
  25
  26 * Each file must end with newline (most editors do that automatically, beware
  27   of Kate).
  28
  29 .Braces and Spaces
  30
  31 * Avoid tricky expressions if possible ;)
  32
  33 * Do not put multiple statements on a single line.
  34 +
  35 [source,c]
  36 ----
  37 /* WRONG */
  38 if (something) do_work();
  39         do_other();
  40
  41 /* RIGHT */
  42 if (something)
  43         do_work();
  44
  45 do_other();
  46 ----
  47
  48 * Each block that has more than one line should be enclosed in
  49   curly braces.
  50 +
  51 Also if one part of if then else is enclosed in
  52 curly braces the other one should be enclosed too.
  53 +
  54 [source,c]
  55 ----
  56 /* WRONG */
  57 if (something)
  58         do_other_thing();
  59         else if (something_else)
  60                 do_thing();
  61         else
  62                 return;
  63
  64 /* RIGHT */
  65 if (something) {
  66         do_other_thing();
  67 } else {
  68         if (something_else)
  69                 do_thing();
  70         else
  71                 return;
  72 }
  73 ----
  74
  75 * On the other hand do not use braces unnecesarily.
  76 +
  77 [source,c]
  78 ----
  79 /* WRONG */
  80 if (something) {
  81         do_work();
  82 }
  83
  84 /* RIGHT */
  85 if (something)
  86         do_work();
  87 ----
  88
  89 * The preffered way of writing switch is as follows:
  90 +
  91 [source,c]
  92 ----
  93 switch (var) {
  94 case XYZ:
  95         do_something():
  96 break;
  97 case ABC:
  98         return 1;
  99 default:
 100 break;
 101 }
 102 ----
 103
 104 TIP: You can use Linux Kernel 'scripts/checkpatch.pl' to check your code.
 105
 106 GFXprim Specific Rules
 107 ^^^^^^^^^^^^^^^^^^^^^^
 108
 109 * Library external API uses CamelCase
 110 ** Together with mandatory 'GP_' prefix.
 111 ** For example 'GP_PixelType', 'GP_Context', etc.
 112 ** We will not change that, get over it. (It could have been worse, trust me.)
 113
 114 * Basic library types are typedefed
 115 ** We have 'GP_Size' and 'GP_Coord' integer types to better distinguish
 116    roles of function parameters.
 117 ** The basic structures are also typedefed so you can wite 'GP_Context'
 118    instead of 'struct GP_Context'.
 119 ** Other uses of typedef are frowned upon.
 120
 121 * When you add an externally visible symbol, i.e. new API function
 122   please add its name into the corresponding file at 'build/syms/'. You may
 123   also run the 'buld/check_symbols.sh' script to check that you haven't
 124   accidentally exposed intenal only interfaces.
 125
 126 Python Coding Style
 127 ~~~~~~~~~~~~~~~~~~~
 128
 129 The Python parts of GFXprim follow mostly coding style outlined in
 130 link:http://www.python.org/dev/peps/pep-0008/[PEP 8].
 131 The major difference is that the default indent is 2 spaces.
 132 All files should be ASCII unless required otherwise.
 133
 134 GFXPrim uses CamelCase as described in the C section.
 135 The names are mostly derived from the corresponding C names without
 136 the 'GP_' prefix.
 137 All wrapped symbols of a module are available in the SWIG modules 'foo.c_foo'
 138 (i.e. 'core.c_core').
 139
 140 Some number and enum types are typedeffed in C, but left as integers
 141 in the Python interface.
 142 All constants are available in 'foo.C' submodules (i.e. 'core.C')
 143 to avoid clutter.
 144
 145 Where this makes sense, functions should be available as methods of
 146 an object (i.e. 'Context.Copy()' rather than 'Copy(context)'). Be Pythonic.
 147