doc/code-style.txt

   1 Waffle's coding style is heavily influenced by the Linux kernel and XCB.
   2
   3 When in doubt, follow the style of nearby code.
   4
   5
   6 Naming
   7 ======
   8 All symbols exposed in the public API must be prefixed with `waffle_` or
   9 `WAFFLE_`.
  10
  11 No camelCase, itIsSoHardToRead, especiallyWhenTheVariableNameContainsAnUpperCaseAcronym.
  12
  13 Function and variable names are lower_case_with_underscores.
  14
  15 Enum and macro names are UPPER_CASE_WITH_UNDERSCORES.
  16
  17
  18 Comments
  19 ========
  20 Non-Doxygen comments begin with '//'. Do not use '/*'-style comments.
  21 There are special exceptions, such as when commenting items in a table. Use
  22 your judgement.
  23
  24 Doxygen comments begin with '///' or '//!'.
  25
  26
  27 Indentation
  28 ===========
  29 Indent 4 spaces. No tabs.
  30
  31 Place a function's return type on its own line. This ensures that all function
  32 names are aligned and makes it easier to quickly find a function when scanning
  33 the source.
  34
  35     void
  36     make_coffee(int x, int y);
  37
  38 If a function prototype has a longwinded parameter list, then indent it like this:
  39
  40     void
  41     make_fancy_coffee(
  42         struct coffee_mug *mug,
  43         struct french_press *press,
  44         struct sugar_dish *sugar);
  45
  46 or this:
  47
  48     void
  49     make_fancy_coffee(struct coffee_mug *mug,
  50                       struct french_press *press,
  51                       struct sugar_dish *sugar);
  52
  53 Indent cases in switch statements. The last case always requires a jump
  54 (break, return, goto).
  55
  56     switch (time) {
  57         case 600:
  58         case 1545:
  59             wake_up();
  60             break;
  61         case 1500:
  62         case 2200:
  63             sleep();
  64             break;
  65         default:
  66             breathe();
  67             break;
  68     }
  69
  70 Don't put multiple statements on a single line.
  71
  72     BAD:
  73         if (condition) do_something;
  74
  75     GOOD:
  76         if (condition) {
  77             do_something;
  78         }
  79
  80
  81 Spaces
  82 ======
  83 Leave no trailing whitespace on end of lines. This can cause spurious commit
  84 conflicts.
  85
  86 A single empty line separates function and struct defintions.
  87
  88 Do not add spaces inside a parenthesized expression.
  89
  90     bad: foo( x, y );
  91
  92 Place a space after these keywords:
  93     if, switch, case, for, do, while
  94
  95 For keywords that are typically used as functions, do not follow the keyword
  96 with a space and do enclose the arguments with parentheses. The keywords are:
  97     sizeof, typeof, alignof, __attribute__
  98
  99 When declaring a variable or argument with pointer type, the '*' goes adjacent
 100 to the variable or argument name.
 101
 102     void
 103     make_fancy_coffee(
 104         struct coffee_mug *mug,
 105         struct french_press *press,
 106         struct sugar_dish *sugar)
 107     {
 108         void *mystery_ingredient = mug + press + sugar;
 109         ...
 110     }
 111
 112 No spaces around unary operators.
 113     --y;
 114     !z;
 115
 116 No spaces around the structure member operators: '.' and '->'.
 117     cow->tail
 118     teapot.spout
 119
 120 Place a single space before and after the binary operators.
 121     a + b
 122     x == y