doc/coding-style.txt

   1 Every project has its coding style, and ConnMan is not an exception. This
   2 document describes the preferred coding style for ConnMan code, in order to keep
   3 some level of consistency among developers so that code can be easily
   4 understood and maintained, and also to help your code survive under
   5 maintainer's fastidious eyes so that you can get a passport for your patch
   6 ASAP.
   7
   8 First of all, ConnMan coding style must follow every rule for Linux kernel
   9 (http://www.kernel.org/doc/Documentation/CodingStyle). There also exists a tool
  10 named checkpatch.pl to help you check the compliance with it. Just type
  11 "checkpatch.pl --no-tree patch_name" to check your patch. In theory, you need
  12 to clean up all the warnings and errors except this one: "ERROR: Missing
  13 Signed-off-by: line(s)". ConnMan does not used Signed-Off lines, so including
  14 them is actually an error.  In certain circumstances one can ignore the 80
  15 character per line limit.  This is generally only allowed if the alternative
  16 would make the code even less readable.
  17
  18 Besides the kernel coding style above, ConnMan has special flavors for its own.
  19 Some of them are mandatory (marked as 'M'), while some others are optional
  20 (marked as 'O'), but generally preferred.
  21
  22 M1: Blank line before and after an if/while/do/for statement
  23 ============================================================
  24 There should be a blank line before if statement unless the if is nested and
  25 not preceded by an expression or variable declaration.
  26
  27 Example:
  28 1)
  29 a = 1;
  30 if (b) {  // wrong
  31
  32 2)
  33 a = 1
  34
  35 if (b) {
  36 }
  37 a = 2;  // wrong
  38
  39 3)
  40 if (a) {
  41         if (b)  // correct
  42
  43 4)
  44 b = 2;
  45
  46 if (a) {        // correct
  47
  48 }
  49
  50 b = 3;
  51
  52 The only exception to this rule applies when a variable is being allocated:
  53 array = g_try_new0(int, 20);
  54 if (array == NULL)      // Correct
  55         return;
  56
  57
  58 M2: Multiple line comment
  59 =========================
  60 If your comments have more then one line, please start it from the second line.
  61
  62 Example:
  63 /*
  64  * first line comment   // correct
  65  * ...
  66  * last line comment
  67  */
  68
  69
  70 M3: Space before and after operator
  71 ===================================
  72 There should be a space before and after each operator.
  73
  74 Example:
  75 a + b;  // correct
  76
  77
  78 M4: Wrap long lines
  79 ===================
  80 If your condition in if, while, for statement or a function declaration is too
  81 long to fit in one line, the new line needs to be indented not aligned with the
  82 body.
  83
  84 Example:
  85 1)
  86 if (call->status == CALL_STATUS_ACTIVE ||
  87         call->status == CALL_STATUS_HELD) {  // wrong
  88         connman_dbus_dict_append();
  89
  90 2)
  91 if (call->status == CALL_STATUS_ACTIVE ||
  92                 call->status == CALL_STATUS_HELD) {  // correct
  93         connman_dbus_dict_append();
  94
  95 3)
  96 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
  97         num sim_ust_service index) // wrong
  98 {
  99         int a;
 100         ...
 101 }
 102
 103 4)
 104 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
 105                                         enum sim_ust_service index) // correct
 106 {
 107         int a;
 108         ...
 109 }
 110
 111 If the line being wrapped is a function call or function declaration, the
 112 preferred style is to indent at least past the opening parenthesis. Indenting
 113 further is acceptable as well (as long as you don't hit the 80 character
 114 limit).
 115
 116 If this is not possible due to hitting the 80 character limit, then indenting
 117 as far as possible to the right without hitting the limit is preferred.
 118
 119 Example:
 120
 121 1)
 122 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
 123                 enum sim_ust_service index); // worse
 124
 125 2)
 126 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
 127                                                 enum sim_ust_service index);
 128                                                 // better
 129
 130 M5: Git commit message 50/72 formatting
 131 =======================================
 132 The commit message header should be within 50 characters. And if you have
 133 detailed explanatory text, wrap it to 72 character.
 134
 135
 136 M6: Space when doing type casting
 137 =================================
 138 There should be a space between new type and variable.
 139
 140 Example:
 141 1)
 142 a = (int *)b;  // wrong
 143 2)
 144 a = (int *) b;  // correct
 145
 146
 147 M7: Don't initialize variable unnecessarily
 148 ===========================================
 149 When declaring a variable, try not to initialize it unless necessary.
 150
 151 Example:
 152 int i = 1;  // wrong
 153
 154 for (i = 0; i < 3; i++) {
 155 }
 156
 157
 158 M8: Use g_try_malloc instead of g_malloc
 159 ========================================
 160 When g_malloc fails, the whole program would exit. Most of time, this is not
 161 the expected behavior, and you may want to use g_try_malloc instead.
 162
 163 Example:
 164 additional = g_try_malloc(len - 1);  // correct
 165 if (additional == NULL)
 166         return FALSE;
 167
 168
 169 M9: Follow the order of include header elements
 170 ===============================================
 171 When writing an include header the various elements should be in the following
 172 order:
 173         - #includes
 174         - forward declarations
 175         - #defines
 176         - enums
 177         - typedefs
 178         - function declarations and inline function definitions
 179
 180
 181 M10: Internal headers must not use include guards
 182 =================================================
 183 Any time when creating a new header file with non-public API, that header
 184 must not contain include guards.
 185
 186
 187 M11: Naming of enums
 188 ====================
 189
 190 Enums must have a descriptive name.  The enum type should be small caps and
 191 it should not be typedef-ed.  Enum contents should be in CAPITAL letters and
 192 prefixed by the enum type name.
 193
 194 Example:
 195
 196 enum animal_type {
 197         ANIMAL_TYPE_FOUR_LEGS,
 198         ANIMAL_TYPE_EIGHT_LEGS,
 199         ANIMAL_TYPE_TWO_LEGS,
 200 };
 201
 202 If the enum contents have values (e.g. from specification) the formatting
 203 should be as follows:
 204
 205 enum animal_type {
 206         ANIMAL_TYPE_FOUR_LEGS =         4,
 207         ANIMAL_TYPE_EIGHT_LEGS =        8,
 208         ANIMAL_TYPE_TWO_LEGS =          2,
 209 };
 210
 211 M12: Enum as switch variable
 212 ====================
 213
 214 If the variable of a switch is an enum, you must not include a default in
 215 switch body. The reason for this is: If later on you modify the enum by adding
 216 a new type, and forget to change the switch accordingly, the compiler will
 217 complain the new added type hasn't been handled.
 218
 219 Example:
 220
 221 enum animal_type {
 222         ANIMAL_TYPE_FOUR_LEGS =         4,
 223         ANIMAL_TYPE_EIGHT_LEGS =        8,
 224         ANIMAL_TYPE_TWO_LEGS =          2,
 225 };
 226
 227 enum animal_type t;
 228
 229 switch (t) {
 230 case ANIMAL_TYPE_FOUR_LEGS:
 231         ...
 232         break;
 233 case ANIMAL_TYPE_EIGHT_LEGS:
 234         ...
 235         break;
 236 case ANIMAL_TYPE_TWO_LEGS:
 237         ...
 238         break;
 239 default:  // wrong
 240         break;
 241 }
 242
 243 However if the enum comes from an external header file outside ConnMan
 244 we cannot make any assumption of how the enum is defined and this
 245 rule might not apply.
 246
 247 M13: Check for pointer being NULL
 248 =================================
 249
 250 When checking if a pointer or a return value is NULL, explicitly compare to
 251 NULL rather than use the shorter check with "!" operator.
 252
 253 Example:
 254 1)
 255 array = g_try_new0(int, 20);
 256 if (!array)     // Wrong
 257         return;
 258
 259 2)
 260 if (!g_at_chat_get_slave(chat)) // Wrong
 261         return -EINVAL;
 262
 263 3)
 264 array = g_try_new0(int, 20);
 265 if (array == NULL)      // Correct
 266         return;
 267
 268
 269 M14: Always use parenthesis with sizeof
 270 =======================================
 271 The expression argument to the sizeof operator should always be in
 272 parenthesis, too.
 273
 274 Example:
 275 1)
 276 memset(stuff, 0, sizeof(*stuff));
 277
 278 2)
 279 memset(stuff, 0, sizeof *stuff); // Wrong
 280
 281
 282 M15: Use void if function has no parameters
 283 ===========================================================
 284 A function with no parameters must use void in the parameter list.
 285
 286 Example:
 287 1)
 288 void foo(void)
 289 {
 290 }
 291
 292 2)
 293 void foo()      // Wrong
 294 {
 295 }
 296
 297 M16: Don't use hex value with shift operators
 298 ==============================================
 299 The expression argument to the shift operators should not be in hex.
 300
 301 Example:
 302
 303 1)
 304 1 << y
 305
 306 2)
 307 0x1 << y        // Wrong
 308
 309 O1: Shorten the name
 310 ====================
 311 Better to use abbreviation, rather than full name, to name a variable,
 312 function, struct, etc.
 313
 314 Example:
 315 supplementary_service  // too long
 316 ss  // better
 317
 318 O2: Try to avoid complex if body
 319 ================================
 320 It's better not to have a complicated statement for if. You may judge its
 321 contrary condition and return | break | continue | goto ASAP.
 322
 323 Example:
 324 1)
 325 if (a) {  // worse
 326         struct voicecall *v;
 327         call = synthesize_outgoing_call(vc, vc->pending);
 328         v = voicecall_create(vc, call);
 329         v->detect_time = time(NULL);
 330         DBG("Registering new call: %d", call->id);
 331         voicecall_dbus_register(v);
 332 } else
 333         return;
 334
 335 2)
 336 if (!a)
 337         return;
 338
 339 struct voicecall *v;
 340 call = synthesize_outgoing_call(vc, vc->pending);
 341 v = voicecall_create(vc, call);
 342 v->detect_time = time(NULL);
 343 DBG("Registering new call: %d", call->id);
 344 voicecall_dbus_register(v);