doc/CODING_STYLE

   1 Clutter Coding Style
   2 -------------------------------------------------------------------------------
   3
   4 This document is intended to be a short description of the preferred
   5 coding style to be used for the Clutter source code.
   6
   7 Coding style is a matter of consistency, readability and maintainance;
   8 coding style is also completely arbitrary and a matter of taste. This
   9 document will use examples at the very least to provide authoritative
  10 and consistent answers to common questions regarding the coding style,
  11 and will also try to identify the allowed exceptions.
  12
  13 The examples will show the preferred coding style; the negative examples
  14 will be clearly identified. Please, don't submit code to Clutter that
  15 looks like any of these.
  16
  17 Part of the rationales for these coding style rules are available either
  18 in the kernel CodingStyle document or in Cairo's CODING_STYLE one.
  19
  20 When in doubt, check the surrounding code and try to imitate it.
  21
  22 Clutter provides an Uncrustify configuration file that tries to match
  23 this document. Since automated tools are not a substitute for human eye,
  24 they should not be entirely relied upon - but they can give an initial
  25 layout for contributors.
  26
  27 + Line width
  28
  29 The maximum line width for source files is 80 characters, whenever possible.
  30 Longer lines are usually an indication that you either need a function
  31 or a pre-processor macro.
  32
  33 + Indentation
  34
  35 Each new level is indented 2 or more spaces than the previous level:
  36
  37   if (condition)
  38     single_statement ();
  39
  40 This can only be achieved using space characters. It may not be achieved
  41 using tab characters alone, or using a combination of spaces and tabs.
  42
  43 Do not change the editor's configuration to change the meaning of a
  44 tab character (see below); code using tabs to indent will not be accepted
  45 into Clutter.
  46
  47 Even if two spaces for each indentation level allows deeper nesting than
  48 8 spaces, Clutter favours self-documenting function names that can take
  49 quite some space. For this reason you should avoid deeply nested code.
  50
  51 + Tab characters
  52
  53 The tab character must always be expanded to spaces. If a literal
  54 tab must be used inside the source, the tab must always be interpreted
  55 according to its traditional meaning:
  56
  57         Advance to the next column which is a multiple of 8.
  58         [ these two lines should be aligned ]
  59
  60 + Braces
  61
  62 Curly braces should not be used for single statement blocks:
  63
  64   if (condition)
  65     single_statement ();
  66   else
  67     another_single_statement (arg1);
  68
  69 In case of multiple statements, curly braces should be put on another
  70 indentation level:
  71
  72   if (condition)
  73     {
  74       statement_1 ();
  75       statement_2 ();
  76       statement_3 ();
  77     }
  78
  79 The "no block for single statements" rule has only three exceptions:
  80
  81   ①  if the single statement covers multiple lines, e.g. for functions with
  82      many arguments, and it is followed by else or else if:
  83
  84   /* valid */
  85   if (condition)
  86     {
  87       a_single_statement_with_many_arguments (some_lengthy_argument,
  88                                               another_lengthy_argument,
  89                                               and_another_one,
  90                                               plus_one);
  91     }
  92   else
  93     another_single_statement (arg1, arg2);
  94
  95   ②  if the condition is composed of many lines:
  96
  97   /* valid */
  98   if (condition1 ||
  99       (condition2 && condition3) ||
 100       condition4 ||
 101       (condition5 && (condition6 || condition7)))
 102     {
 103       a_single_statement ();
 104     }
 105
 106   ③  Nested if's, in which case the block should be placed on the
 107      outermost if:
 108
 109   /* valid */
 110   if (condition)
 111     {
 112       if (another_condition)
 113         single_statement ();
 114       else
 115         another_single_statement ();
 116     }
 117
 118   /* invalid */
 119   if (condition)
 120     if (another_condition)
 121       single_statement ();
 122     else if (yet_another_condition)
 123       another_single_statement ();
 124
 125 In general, new blocks should be placed on a new indentation level,
 126 like:
 127
 128   int retval = 0;
 129
 130   statement_1 ();
 131   statement_2 ();
 132
 133   {
 134     int var1 = 42;
 135     gboolean res = FALSE;
 136
 137     res = statement_3 (var1);
 138
 139     retval = res ? -1 : 1;
 140   }
 141
 142 While curly braces for function definitions should rest on a new line
 143 they should not add an indentation level:
 144
 145   /* valid */
 146   static void
 147   my_function (int argument)
 148   {
 149     do_my_things ();
 150   }
 151
 152   /* invalid */
 153   static void
 154   my_function (int argument) {
 155     do_my_things ();
 156   }
 157
 158   /* invalid */
 159   static void
 160   my_function (int argument)
 161     {
 162       do_my_things ();
 163     }
 164
 165 Curly braces must not be placed on the same line as a condition:
 166
 167   /* invalid */
 168   if (condition) {
 169     statement_1 ();
 170     statement_2 ();
 171   }
 172
 173 + Conditions
 174
 175 Do not check boolean values for equality:
 176
 177   /* invalid */
 178   if (condition == TRUE)
 179     do_foo ();
 180
 181   /* valid */
 182   if (another_condition)
 183     do_bar ();
 184
 185 Even if C handles NULL equality like a boolean, be explicit:
 186
 187   /* valid */
 188   if (some_pointer == NULL)
 189     do_blah ();
 190
 191   /* invalid */
 192   if (some_other_pointer)
 193     do_blurp ();
 194
 195 In case of conditions split over multiple lines, the logical operators should
 196 always go at the end of the line:
 197
 198   /* invalid */
 199   if (condition1
 200       || condition2
 201       || condition3)
 202     {
 203       do_foo ();
 204     }
 205
 206   /* valid */
 207   if (condition1 &&
 208       condition2 &&
 209       (condition3 || (condition4 && condition5)))
 210     {
 211       do_blah ();
 212     }
 213
 214 + Functions
 215
 216 Functions should be declared by placing the returned value on a separate
 217 line from the function name:
 218
 219   void
 220   my_function (void)
 221   {
 222   }
 223
 224 The arguments list must be broken into a new line for each argument,
 225 with the argument names right aligned, taking into account pointers:
 226
 227   void
 228   my_function (some_type_t     type,
 229                another_type_t *a_pointer,
 230                final_type_t    another_type)
 231   {
 232   }
 233
 234 The alignment also holds when invoking a function without breaking the
 235 80 characters limit:
 236
 237   align_function_arguments (first_argument,
 238                             second_argument,
 239                             third_argument);
 240
 241 To respect the 80 characters limit do not break the function name from
 242 the arguments:
 243
 244   /* invalid */
 245   a_very_long_function_name_with_long_parameters
 246     (argument_the_first, argument_the_second);
 247
 248   /* valid */
 249   first_a = argument_the_first;
 250   second_a = argument_the_second;
 251   a_very_long_function_name_with_long_parameters (first_a, second_a);
 252
 253 + Whitespace
 254
 255 Always put a space before a parenthesis but never after:
 256
 257   /* valid */
 258   if (condition)
 259     do_my_things ();
 260
 261   /* valid */
 262   switch (condition)
 263     {
 264     }
 265
 266   /* invalid */
 267   if(condition)
 268     do_my_things();
 269
 270   /* invalid */
 271   if ( condition )
 272     do_my_things ( );
 273
 274 A switch() should open a block on a new indentation level, and each case
 275 should start on the same indentation level as the curly braces, with the
 276 case block on a new indentation level:
 277
 278   /* valid */
 279   switch (condition)
 280     {
 281     case FOO:
 282       do_foo ();
 283       break;
 284
 285     case BAR:
 286       do_bar ();
 287       break;
 288     }
 289
 290   /* invalid */
 291   switch (condition) {
 292     case FOO: do_foo (); break;
 293     case BAR: do_bar (); break;
 294   }
 295
 296   /* invalid */
 297   switch (condition)
 298     {
 299     case FOO: do_foo ();
 300       break;
 301     case BAR: do_bar ();
 302       break;
 303     }
 304
 305   /* invalid */
 306   switch (condition)
 307     {
 308       case FOO:
 309       do_foo ();
 310       break;
 311       case BAR:
 312       do_bar ();
 313       break;
 314     }
 315
 316 It is preferable, though not mandatory, to separate the various cases with
 317 a newline:
 318
 319   switch (condition)
 320     {
 321     case FOO:
 322       do_foo ();
 323       break;
 324
 325     case BAR:
 326       do_bar ();
 327       break;
 328
 329     default:
 330       do_default ();
 331     }
 332
 333 The 'break' statement for the default: case is not mandatory.
 334
 335 If a case block needs to declare new variables, the same rules as the
 336 inner blocks (see above) apply; the break statement should be placed
 337 outside of the inner block:
 338
 339   switch (condition)
 340     {
 341     case FOO:
 342       {
 343         int foo;
 344
 345         foo = do_foo ();
 346       }
 347       break;
 348
 349     ...
 350     }
 351
 352 When declaring a structure type use newlines to separate logical sections
 353 of the structure:
 354
 355   struct _ClutterActorPrivate
 356   {
 357     /* fixed position */
 358     ClutterUnit fixed_x;
 359     ClutterUnit fixed_y;
 360
 361     ClutterRequestMode request_mode;
 362
 363     /* requisition sizes */
 364     ClutterUnit request_width_for_height;
 365     ClutterUnit request_min_width;
 366     ClutterUnit request_natural_width;
 367     ClutterUnit request_height_for_width;
 368     ClutterUnit request_min_height;
 369     ClutterUnit request_natural_height;
 370
 371     ClutterActorBox allocation;
 372
 373     ...
 374   };
 375
 376 Do not eliminate whitespace and newlines just because something would
 377 fit on 80 characters:
 378
 379   /* invalid */
 380   if (condition) foo (); else bar ();
 381
 382 Do eliminate trailing whitespace on any line, preferably as a separate
 383 patch or commit. Never use empty lines at the beginning or at the end of
 384 a file.
 385
 386 Do enable the default git pre-commit hook that detect trailing
 387 whitespace for you and help you to avoid corrupting Clutter's tree with
 388 it. Do that as follows:
 389
 390   chmod a+x .git/hooks/pre-commit
 391
 392 You might also find the git-stripspace utility helpful which acts as a
 393 filter to remove trailing whitespace as well as initial, final, and
 394 duplicate blank lines.
 395
 396 + Headers
 397
 398 Headers are special, for Clutter, in that they don't have to obey the
 399 80 characters limit. The only major rule for headers is that the functions
 400 definition should be vertically aligned in three columns:
 401
 402   return value          function_name           (type   argument,
 403                                                  type   argument,
 404                                                  type   argument);
 405
 406 The maximum width of each column is given by the longest element in the
 407 column:
 408
 409   void         clutter_type_set_property (ClutterType  *type,
 410                                           const gchar  *value,
 411                                           GError      **error);
 412   const gchar *clutter_type_get_property (ClutterType  *type);
 413
 414 It is also possible to align the columns to the next tab:
 415
 416   void          clutter_type_set_prop           (ClutterType *type,
 417                                                  gfloat       value);
 418   gfloat        clutter_type_get_prop           (ClutterType *type);
 419   gint          clutter_type_update_foobar      (ClutterType *type);
 420
 421 Public headers should never be included directly:
 422
 423   #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
 424   #error "Only <clutter/clutter.h> can be included directly."
 425   #endif
 426
 427 Public headers should also have inclusion guards (for internal usage)
 428 and C++ guards:
 429
 430   #ifndef __CLUTTER_HEADER_H__
 431   #define __CLUTTER_HEADER_H__
 432
 433   #include <clutter/clutter-actor.h>
 434
 435   G_BEGIN_DECLS
 436
 437   ...
 438
 439   G_END_DECLS
 440
 441   #endif /* __CLUTTER_HEADER_H__ */
 442
 443 + Includes
 444
 445 Clutter source files should never include the global clutter.h header, but
 446 instead include the individual headers that are needed. Every file must
 447 include config.h first, then its own header, then other Clutter headers
 448 that it needs, then system and third-party headers that it needs.
 449
 450   /* valid */
 451   #include "config.h"
 452
 453   #include "clutter-foo.h"
 454
 455   #include "clutter-actor.h"
 456   #include "clutter-container.h"
 457
 458   ...
 459
 460   #include <string.h>
 461
 462 + GObject
 463
 464 GObject classes definition and implementation require some additional
 465 coding style notices.
 466
 467 Typedef declarations should be placed at the beginning of the file:
 468
 469   typedef struct _ClutterActor          ClutterActor;
 470   typedef struct _ClutterActorPrivate   ClutterActorPrivate;
 471   typedef struct _ClutterActorClass     ClutterActorClass;
 472
 473 This includes enumeration types:
 474
 475   typedef enum {
 476     CLUTTER_REQUEST_WIDTH_FOR_HEIGHT,
 477     CLUTTER_REQUEST_HEIGHT_FOR_WIDTH
 478   } ClutterRequestMode;
 479
 480 And callback types:
 481
 482   typedef void (* ClutterCallback) (ClutterActor *actor,
 483                                     gpointer      user_data);
 484
 485 Instance structures should only contain the parent type and a pointer to a
 486 private data structure, and they should be annotated as "private":
 487
 488   struct _ClutterRectangle
 489   {
 490     /*< private >*/
 491     ClutterActor parent_instance;
 492
 493     ClutterRectanglePrivate *priv;
 494   };
 495
 496 All the properties should be stored inside the private data structure, which
 497 is defined inside the source file - or, if needed, inside a private header
 498 file; the private header filename must end with "-private.h" and must not be
 499 installed.
 500
 501 The private data structure should only be accessed internally using the
 502 pointer inside the instance structure, and never using the
 503 G_TYPE_INSTANCE_GET_PRIVATE() macro or the g_type_instance_get_private()
 504 function.
 505
 506 Always use the G_DEFINE_TYPE(), G_DEFINE_TYPE_WITH_CODE() macros, or
 507 their abstract variants G_DEFINE_ABSTRACT_TYPE() and
 508 G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
 509
 510 Avoid forward declaration for functions: use the G_DEFINE_* macros right
 511 after the private types, variables and macros declarations.
 512
 513 Interface types should always have the dummy typedef for cast purposes:
 514
 515         typedef struct _ClutterFoo              ClutterFoo;
 516
 517 The interface structure should have "Iface" postfixed to the dummy typedef:
 518
 519         typedef struct _ClutterFooIface         ClutterFooIface;
 520
 521 Interfaces must have the following macros:
 522
 523         - Macro:                                - Expands to:
 524         • CLUTTER_TYPE_<iface_name>             <iface_name>_get_type
 525         • CLUTTER_<iface_name>                  G_TYPE_CHECK_INSTANCE_CAST
 526         • CLUTTER_IS_<iface_name>               G_TYPE_CHECK_INSTANCE_TYPE
 527         • CLUTTER_<iface_name>_GET_IFACE        G_TYPE_INSTANCE_GET_INTERFACE
 528
 529 + Memory allocation
 530
 531 When dynamically allocating data on the heap either use g_new() or,
 532 if allocating multiple small data structures, g_slice_new().
 533
 534 Public structure types should always be returned after being zero-ed,
 535 either explicitly for each member, or by using g_new0() or g_slice_new0().
 536
 537 + Macros
 538
 539 Try to avoid private macros unless strictly necessary. Remember to #undef
 540 them at the end of a block or a series of functions needing them.
 541
 542 Inline functions are usually preferable to private macros.
 543
 544 Public macros should not be used unless they evaluate to a constant.
 545
 546 + Public API
 547
 548 Avoid exporting variables as public API, since this is cumbersome on some
 549 platforms. It is always preferable to add getters and setters instead.
 550
 551 + Private API
 552
 553 Non-exported functions that are needed in more than one source file
 554 should be named "_clutter_...", and declared in a private header file.
 555
 556 Underscore-prefixed functions are never exported.
 557
 558 Non-exported functions that are only needed in one source file
 559 should be declared static.
 560
 561 + Documentation
 562
 563 All public APIs must have gtk-doc comments. For functions, these should
 564 be placed in the source file, directly above the function.
 565
 566   /* valid */
 567   /**
 568    * clutter_get_flow:
 569    * @actor: a #ClutterActor
 570    *
 571    * Gets the flow of an actor.
 572    *
 573    * Note that flows may be laminar or turbulent...
 574    *
 575    * Return value: (transfer none): the flow of @actor
 576    */
 577   ClutterFlow *
 578   clutter_get_flow (ClutterActor *actor)
 579   {
 580     ...
 581   }
 582
 583 Doc comments for macros, function types, class structs, etc should be
 584 placed next to the definitions, typically in headers.
 585
 586 Section introductions should be placed in the source file they describe,
 587 after the license header:
 588
 589   /* valid */
 590   /**
 591    * SECTION:clutter-align-constraint
 592    * @Title: ClutterAlignConstraint
 593    * @Short_Description: A constraint aligning the position of an actor
 594    *
 595    * #ClutterAlignConstraint is a #ClutterConstraint that aligns the position
 596    * of the #ClutterActor to which it is applied to the size of another
 597    * #ClutterActor using an alignment factor
 598    *
 599    * [...]
 600    */
 601
 602 To properly document a new function, macro, function type or struct,
 603 it needs to be listed in the clutter-sections.txt file.
 604
 605 To properly document a new class, it needs to be given its own section
 606 in clutter-sections.txt, needs to be included in clutter-docs.xml, and the
 607 get_type function needs to listed in clutter.types.
 608
 609 + Old code
 610
 611 It is ok to update the style of a code block or function when you
 612 are touching it anyway, but sweeping whitespace changes obscure the
 613 git history and should be avoided.