CODING_STYLE

   1 GENIVI Boot Manager Coding Style
   2 ================================
   3
   4 This document intends to give information about the coding style to be
   5 used when contributing code to the GENIVI Boot Manager. It does not
   6 claim to be complete. Parts of it are taken or inspired from the Clutter
   7 coding style document.
   8
   9 In the following, the most important requirements for writing consistent
  10 code for the GENIVI Boot Manager are explained.
  11
  12 Table of Contents:
  13   * Line Width
  14   * Whitespace
  15   * Indentation and Braces
  16   * Functions and Braces
  17   * Empty Lines
  18   * Variable Declarations
  19   * Assertions
  20   * More on Conditions
  21   * Header Files
  22   * Loops and Loop Termination
  23
  24
  25 Line Width
  26 ==========
  27
  28 The maximum line width for source files is 90 characters. This limit may
  29 be exceeded when there is no way around it. Accepted ways to wrap long
  30 lines caused by function calls are
  31
  32   result = some_function_with_a_very_long_name (first_parameter,
  33                                                 second_parameter,
  34                                                 third_parameter);
  35
  36 and
  37
  38   long_result_variable =
  39     some_function_with_a_very_long_name (first_parameter,
  40                                          second_parameter,
  41                                          third_parameter);
  42
  43 where the result variable name is too long to fit the function call
  44 into the 90 characters limit even when wrapping the parameters.
  45
  46 Do not separate the function name from its arguments like this:
  47
  48   /* bad */
  49   some_function_with_a_long_name
  50     (long_argument_name1, long_argument_name2);
  51
  52 Instead, consider using shorter variable names as aliases:
  53
  54   /* good */
  55   short1 = long_argument_name1;
  56   short2 = long_argument_name2;
  57   some_function_with_a_long_name (short1, short2);
  58
  59 The line width limit of 90 characters does not apply to header files.
  60 However the alignment and parameter indentation rules explained in the
  61 section "Functions and Braces" still apply to header files.
  62
  63
  64 Whitespace
  65 ==========
  66
  67 Always insert a space before a parenthesis but never after or
  68 between the opening or closing parenthesis and a parameter.
  69
  70   /* good */
  71   if (condition)
  72     foo (argument1, argument2);
  73
  74   /* bad */
  75   if(condition)
  76     foo(argument1, argument2);
  77
  78   /* bad */
  79   if ( condition )
  80     foo ( argument1, argument 2 );
  81
  82
  83 Indentation and Braces
  84 ======================
  85
  86 Use spaces only, tabs are not allowed. The indentation for each level is
  87 2 spaces in addition to the previous level. Braces add another level of
  88 indentation. Valid indentations and uses of braces are:
  89
  90 Single-line statements:
  91
  92   /* good */
  93   if (condition)
  94     single_line_statement ();
  95
  96 Multiple statements:
  97
  98   /* good */
  99   if (condition)
 100     {
 101       a_statement ();
 102       another_statement ();
 103     }
 104
 105 Multiple and single statements:
 106
 107   /* good */
 108   if (condition)
 109     {
 110       a_statement ();
 111       another_statement ();
 112     }
 113   else
 114     {
 115       one_more_statement ();
 116     }
 117
 118 Do and while loops:
 119
 120   /* good */
 121   while (foo)
 122     {
 123       bar ();
 124     }
 125
 126   /* good */
 127   do
 128     {
 129       bar ();
 130     }
 131   while (foo);
 132
 133 Switch statements:
 134
 135   /* good */
 136   switch (condition)
 137     {
 138     case FOO:
 139       do_something ();
 140       break;
 141     case BAR:
 142       do_something_else ();
 143       break;
 144     default:
 145       do_whatever_you_need_to_do ();
 146       break;
 147     }
 148
 149   /* bad */
 150   switch (condition) {
 151     case FOO:
 152       do_something ();
 153       break;
 154   }
 155
 156   /* bad */
 157   switch (condition)
 158     {
 159       case FOO:
 160         do_something ();
 161         break;
 162     }
 163
 164   /* bad */
 165   switch (condition)
 166     {
 167     case FOO: do_something ();
 168       break;
 169     }
 170
 171   /* bad */
 172   switch (condition)
 173     {
 174       case FOO:
 175       do_something ();
 176       break;
 177     }
 178
 179 Nested if statements:
 180
 181   /* good */
 182   if (condition)
 183     {
 184       /* here the same rules as on the top level apply again */
 185       if (another_condition)
 186         single_statement ();
 187       else if (yet_another_condition)
 188         another_single_statement ();
 189     }
 190
 191 Do not put curly braces into the same line as the condition:
 192
 193   /* bad */
 194   if (condition) {
 195      ...
 196   }
 197
 198 Do not asymmetrically use and not use braces:
 199
 200   /* bad */
 201   if (condition)
 202     {
 203       /* multiple statements */
 204     }
 205   else
 206     single_statement ();
 207
 208 If there are multiple conditions in a single if statement spread across
 209 more than one line, always use curly braces:
 210
 211   /* good */
 212   if (condition1
 213       && condition2)
 214   {
 215     /* multiple or single statement(s) */
 216   }
 217
 218
 219 Functions and Braces
 220 ====================
 221
 222 Braces in function definitions are not indented. Parameters are to be
 223 wrapped and aligned so that the end results looks like this:
 224
 225 Function declarations:
 226
 227   /* good */
 228   static gchar   *some_type_your_function             (SomeType *object,
 229                                                        int       another parameter,
 230                                                        gchar   **and_another_one);
 231   static gboolean some_type_some_longer_function_name (SomeType *object);
 232
 233 Function definitions:
 234
 235   /* good */
 236   static gchar *
 237   some_type_your_function (SomeType *object,
 238                            int       another_parameter,
 239                            gchar   **and_another_one)
 240   {
 241     /* declarations */
 242     /* assertions */
 243     /* actual code */
 244   }
 245
 246 Do not declare functions like this:
 247
 248   /* bad */
 249   static gchar *some_type_your_function (SomeType *object,
 250                                          int another parameter,
 251                                          gchar **and_another_one);
 252   static gboolean some_type_some_longer_function_name (SomeType *object);
 253
 254 Or like this:
 255
 256   /* bad */
 257   static gchar *some_type_your_function (SomeType *object, int another parameter, gchar **and_another_one);
 258   static gboolean some_type_some_longer_function_name (SomeType *object);
 259
 260
 261 Empty Lines
 262 ===========
 263
 264 Between declarations of groups of structs, enums, functions, static
 265 variables and macros there have to be three empty lines to make the
 266 different items easier to spot and distinguish. There also have to be
 267 three empty lines between function definitions.
 268
 269 Also, when declaring data structures, use newlines to separate logical
 270 sections of member variables:
 271
 272   struct _LucHandlerService
 273   {
 274     /* Current LUC content */
 275     GHashTable       *current_content;
 276     GSettings        *settings;
 277
 278     /* NSM shutdown consumer */
 279     ShutdownConsumer *shutdown_consumer;
 280
 281     /* protection against threads */
 282     GMutex           *mutex;
 283   };
 284
 285
 286 Variable Declarations
 287 =====================
 288
 289 Variables may only be declared at the top of a function. Variable
 290 declarations in blocks (code surrounded by braces) are not allowed.
 291
 292 Declarations follow special alignment and sorting rules. The sorting
 293 order of declarations is determined by:
 294
 295   1. number of characters of the variable type
 296   2. ascending alphabetical order of the type (case-insensitive)
 297   3. ascending alphabetical order of the variable name
 298
 299 Here is an example of how a variable declaration sequence has to
 300 look like:
 301
 302   GbmgrLegacyAppHandlerService *service;
 303   NSMShutdownConsumer          *consumer;
 304   const gchar                  *object_name;
 305   GVariant                     *variant;
 306   gchar                        *name;
 307   guint                         n;
 308
 309
 310 Assertions
 311 ==========
 312
 313 In order to make it easier to detect broken code paths, assertions in
 314 the form of g_return_if_fail() and g_return_val_if_fail() statements are
 315 used in almost all methods. When implementing new methods in your code,
 316 please make sure to check the input parameters for type incompatiblities
 317 or memory corruption.
 318
 319
 320 More on Conditions
 321 ==================
 322
 323 Do not check boolean values for equality like this:
 324
 325   /* bad */
 326   if (condition == TRUE)
 327     ...
 328
 329 Instead, just do it like this:
 330
 331   /* good */
 332   if (condition)
 333     ...
 334
 335 Be explicit when checking pointers however:
 336
 337   /* good */
 338   if (some_pointer == NULL)
 339     ...
 340
 341   /* good */
 342   if (some_pointer != NULL)
 343     ...
 344
 345 Do not simply do it like this:
 346
 347   /* bad */
 348   if (some_pointer)
 349     ...
 350
 351 If you have so many conditions in an if statement that you need to split
 352 them up into multiple lines, the logical operatiors should always be
 353 placed at the beginning of the line, like this:
 354
 355   /* good */
 356   if (condition1
 357       || condition 2
 358       || condition 3)
 359   {
 360     ...
 361   }
 362
 363 Don't place the logical operators at the end of the line:
 364
 365   /* bad */
 366   if (condition1 ||
 367       condition2 ||
 368       conidition3)
 369   {
 370     ...
 371   }
 372
 373
 374 Header Files
 375 ============
 376
 377 Header files should always include the following code in addition to the
 378 license header (example for gbmgr-data-structure.h):
 379
 380   #ifndef __GBMGR_DATA_STRUCTURE_H__
 381   #define __GBMGR_DATA_STRUCTURE_H__
 382
 383   #include <something-that-also-includes-glib-object.h>
 384
 385   G_BEGIN_DECLS
 386
 387   ...
 388
 389   G_END_DECLS
 390
 391   #endif /* !__GBMGR_DATA_STRUCTURE_H__ */
 392
 393
 394
 395 Loops and Loop Termination
 396 ==========================
 397
 398 When writing loops, try to avoid break statements. Instead of breaking
 399 on some condition move the condition into the loop header to make more
 400 clear when the loop is supposed to be terminated.
 401
 402 So, instead of doing
 403
 404   /* bad */
 405   for (n = 0; n < some_value; ++n)
 406     {
 407       if (some_other_condition)
 408         break;
 409
 410       ...
 411     }
 412
 413 do it like this:
 414
 415   /* good */
 416   for (n = 0; !some_other_condition && n < some_value; ++n)
 417     {
 418       ...
 419     }
 420
 421 If the loop header exceeds the 90 character limit per line, split it up
 422 into multiple lines (in which case you are required to add curly braces
 423 of course):
 424
 425   /* good */
 426   for (n = 0;
 427        !some_other_condition && n < some_value;
 428        ++n)
 429     {
 430       ...
 431     }
 432
 433 Try to avoid while loops where you can. Some GLib data structures
 434 such as iterators encourage the use of while loops. In those cases it's
 435 ok not to use for loops.