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