doc/coding-style.txt

   1 BlueZ coding style
   2 ******************
   3
   4 Every project has its coding style, and BlueZ is not an exception. This
   5 document describes the preferred coding style for BlueZ code, in order to keep
   6 some level of consistency among developers so that code can be easily
   7 understood and maintained.
   8
   9 First of all, BlueZ coding style must follow every rule for Linux kernel
  10 (http://www.kernel.org/doc/Documentation/CodingStyle). There also exists a tool
  11 named checkpatch.pl to help you check the compliance with it. Just type
  12 "checkpatch.pl --no-tree patch_name" to check your patch. In theory, you need
  13 to clean up all the warnings and errors except this one: "ERROR: Missing
  14 Signed-off-by: line(s)". BlueZ does not used Signed-Off lines, so including
  15 them is actually an error.  In certain circumstances one can ignore the 80
  16 character per line limit.  This is generally only allowed if the alternative
  17 would make the code even less readable.
  18
  19 Besides the kernel coding style above, BlueZ has special flavors for its own.
  20 Some of them are mandatory (marked as 'M'), while some others are optional
  21 (marked as 'O'), but generally preferred.
  22
  23 M1: Blank line before and after an if/while/do/for statement
  24 ============================================================
  25
  26 There should be a blank line before if statement unless the if is nested and
  27 not preceded by an expression or variable declaration.
  28
  29 Example:
  30 1)
  31 a = 1;
  32 if (b) {  // wrong
  33
  34 2)
  35 a = 1
  36
  37 if (b) {
  38 }
  39 a = 2;  // wrong
  40
  41 3)
  42 if (a) {
  43         if (b)  // correct
  44
  45 4)
  46 b = 2;
  47
  48 if (a) {        // correct
  49
  50 }
  51
  52 b = 3;
  53
  54 The only exception to this rule applies when a variable is being checked for
  55 errors as such:
  56
  57 err = stat(filename, &st);
  58 if (err || !S_ISDIR(st.st_mode))
  59         return;
  60
  61 M2: Multiple line comment
  62 =========================
  63
  64 If your comment has more than one line, please start it from the second line.
  65
  66 Example:
  67 /*
  68  * first line comment   // correct
  69  * ...
  70  * last line comment
  71  */
  72
  73
  74 M3: Space before and after operator
  75 ===================================
  76
  77 There should be a space before and after each operator.
  78
  79 Example:
  80 a + b;  // correct
  81
  82
  83 M4: Wrap long lines
  84 ===================
  85
  86 If your condition in if, while, for statement or a function declaration is too
  87 long to fit in one line, the new line needs to be indented not aligned with the
  88 body.
  89
  90 Example:
  91 1)
  92 if ((adapter->supported_settings & MGMT_SETTING_SSP) &&
  93         !(adapter->current_settings & MGMT_SETTING_SSP)) // wrong
  94
  95 2)
  96 if ((adapter->supported_settings & MGMT_SETTING_SSP) &&
  97                                 !(adapter->current_settings & MGMT_SETTING_SSP))
  98
  99 3)
 100 void btd_adapter_register_pin_cb(struct btd_adapter *adapter,
 101                                  btd_adapter_pin_cb_t cb) // wrong
 102
 103 4)
 104 void btd_adapter_register_pin_cb(struct btd_adapter *adapter,
 105                                                         btd_adapter_pin_cb_t cb)
 106
 107 The referred style for line wrapping is to indent as far as possible to the
 108 right without hitting the 80 columns limit.
 109
 110 M5: Space when doing type casting
 111 =================================
 112
 113 There should be a space between new type and variable.
 114
 115 Example:
 116 1)
 117 a = (int *)b;  // wrong
 118 2)
 119 a = (int *) b;  // correct
 120
 121
 122 M6: Don't initialize variable unnecessarily
 123 ===========================================
 124
 125 When declaring a variable, try not to initialize it unless necessary.
 126
 127 Example:
 128 int i = 1;  // wrong
 129
 130 for (i = 0; i < 3; i++) {
 131 }
 132
 133 M7: Follow the order of include header elements
 134 ===============================================
 135
 136 When writing an include header the various elements should be in the following
 137 order:
 138         - #includes
 139         - forward declarations
 140         - #defines
 141         - enums
 142         - typedefs
 143         - function declarations and inline function definitions
 144
 145 M8: Internal headers must not use include guards
 146 ================================================
 147
 148 Any time when creating a new header file with non-public API, that header
 149 must not contain include guards.
 150
 151 M9: Naming of enums
 152 ===================
 153
 154 Enums must have a descriptive name.  The enum type should be small caps and
 155 it should not be typedef-ed.  Enum contents should be in CAPITAL letters and
 156 prefixed by the enum type name.
 157
 158 Example:
 159
 160 enum animal_type {
 161         ANIMAL_TYPE_FOUR_LEGS,
 162         ANIMAL_TYPE_EIGHT_LEGS,
 163         ANIMAL_TYPE_TWO_LEGS,
 164 };
 165
 166 If the enum contents have values (e.g. from specification) the formatting
 167 should be as follows:
 168
 169 enum animal_type {
 170         ANIMAL_TYPE_FOUR_LEGS =         4,
 171         ANIMAL_TYPE_EIGHT_LEGS =        8,
 172         ANIMAL_TYPE_TWO_LEGS =          2,
 173 };
 174
 175 M10: Enum as switch variable
 176 ============================
 177
 178 If the variable of a switch is an enum, you must include all values in
 179 switch body even if providing default. This is enforced by compiler option
 180 enabling extra warning in such case. The reason for this is to ensure that if
 181 later on enum is modified and one forget to change the switch accordingly, the
 182 compiler will complain the new added type hasn't been handled.
 183
 184 Example:
 185
 186 enum animal_type {
 187         ANIMAL_TYPE_FOUR_LEGS =         4,
 188         ANIMAL_TYPE_EIGHT_LEGS =        8,
 189         ANIMAL_TYPE_TWO_LEGS =          2,
 190 };
 191
 192 enum animal_type t;
 193
 194 switch (t) { // OK
 195 case ANIMAL_TYPE_FOUR_LEGS:
 196         ...
 197         break;
 198 case ANIMAL_TYPE_EIGHT_LEGS:
 199         ...
 200         break;
 201 case ANIMAL_TYPE_TWO_LEGS:
 202         ...
 203         break;
 204 default:
 205         break;
 206 }
 207
 208 switch (t) { // Wrong
 209 case ANIMAL_TYPE_FOUR_LEGS:
 210         ...
 211         break;
 212 case ANIMAL_TYPE_TWO_LEGS:
 213         ...
 214         break;
 215 default:
 216         break;
 217 }
 218
 219 However if the enum comes from an external header file outside BlueZ, such as
 220 Android headers, we cannot make any assumption of how the enum is defined and
 221 this rule might not apply.
 222
 223 M11: Always use parenthesis with sizeof
 224 =======================================
 225
 226 The expression argument to the sizeof operator should always be in
 227 parenthesis, too.
 228
 229 Example:
 230 1)
 231 memset(stuff, 0, sizeof(*stuff));
 232
 233 2)
 234 memset(stuff, 0, sizeof *stuff); // Wrong
 235
 236 M12: Use void if function has no parameters
 237 ===========================================
 238
 239 A function with no parameters must use void in the parameter list.
 240
 241 Example:
 242 1)
 243 void foo(void)
 244 {
 245 }
 246
 247 2)
 248 void foo()      // Wrong
 249 {
 250 }
 251
 252 O1: Try to avoid complex if body
 253 ================================
 254
 255 It's better not to have a complicated statement for if. You may judge its
 256 contrary condition and return | break | continue | goto ASAP.
 257
 258 Example:
 259 1)
 260 if (device) {  // worse
 261         memset(&eir_data, 0, sizeof(eir_data));
 262         if (eir_len > 0)
 263                 eir_parse(&eir_data, ev->eir, eir_len);
 264         ...
 265 } else {
 266         error("Unable to get device object for %s", addr);
 267         return;
 268 }
 269
 270 2)
 271 if (!device) {
 272         error("Unable to get device object for %s", addr);
 273         return;
 274 }
 275
 276 memset(&eir_data, 0, sizeof(eir_data));
 277 if (eir_len > 0)
 278         eir_parse(&eir_data, ev->eir, eir_len);
 279 ...