CODING-STYLE 15.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423
GTK+ Coding Style
-------------------------------------------------------------------------------

This document is intended to be a short description of the preferred
coding style to be used for the GTK+ source code. It was strongly
inspired by Clutter's CODING_STYLE.

Coding style is a matter of consistency, readability and maintainance;
coding style is also completely arbitrary and a matter of taste. This
document will use examples at the very least to provide authoritative
and consistent answers to common questions regarding the coding style,
and will also try to identify the allowed exceptions.

The examples will show the preferred coding style; the negative examples
will be clearly identified. Please, don't submit code to GTK+ that
looks like any of these.

Part of the rationales for these coding style rules are available either
in the kernel CodingStyle document or in Cairo's CODING_STYLE one.

When in doubt, check the surrounding code and try to imitate it.

+ Line width

The maximum line width for source files is 80 characters, whenever possible.
Longer lines are usually an indication that you either need a function
or a pre-processor macro.

+ Indentation

Each new level is indented 2 or more spaces than the previous level:

  if (condition)
    single_statement ();

This can only be achieved using space characters. It may not be achieved
using tab characters alone, or using a combination of spaces and tabs.

Do not change the editor's configuration to change the meaning of a
tab character (see below); code using tabs to indent will not be accepted
into GTK+.

Even if two spaces for each indentation level allows deeper nesting than
8 spaces, GTK+ favours self-documenting function names that can take
quite some space. For this reason you should avoid deeply nested code.

+ Tab characters

The tab character must always be expanded to spaces. If a literal
tab must be used inside the source, the tab must always be interpreted
according to its traditional meaning:

	Advance to the next column which is a multiple of 8.
        [ these two lines should be aligned ]

+ Braces

Curly braces should not be used for single statement blocks:

  if (condition)
    single_statement ();
  else
    another_single_statement (arg1);

In case of multiple statements, curly braces should be put on another
indentation level:

  if (condition)
    {
      statement_1 ();
      statement_2 ();
      statement_3 ();
    }

The "no block for single statements" rule has only four exceptions:

  ①  if the single statement covers multiple lines, e.g. for functions with
     many arguments, and it is followed by else or else if:

  /* valid */
  if (condition)
    {
      a_single_statement_with_many_arguments (some_lengthy_argument,
                                              another_lengthy_argument,
                                              and_another_one,
                                              plus_one);
    }
  else
    another_single_statement (arg1, arg2);

  ②  if the condition is composed of many lines:

  /* valid */
  if (condition1 ||
      (condition2 && condition3) ||
      condition4 ||
      (condition5 && (condition6 || condition7)))
    {
      a_single_statement ();
    }

  ③  Nested if's, in which case the block should be placed on the
     outermost if:

  /* valid */
  if (condition)
    {
      if (another_condition)
        single_statement ();
      else
        another_single_statement ();
    }

  /* invalid */
  if (condition)
    if (another_condition)
      single_statement ();
    else if (yet_another_condition)
      another_single_statement ();

  ④  If either side of an if-else statement has braces, both sides
     should, to match up indentation:

  /* valid */
  if (condition)
    {
      foo ();
      bar ();
    }
  else
    {
      baz ();
    }

  /* invalid */
  if (condition)
    {
      foo ();
      bar ();
    }
  else
    baz ();

In general, new blocks should be placed on a new indentation level,
like:

  int retval = 0;

  statement_1 ();
  statement_2 ();

  {
    int var1 = 42;
    gboolean res = FALSE;

    res = statement_3 (var1);

    retval = res ? -1 : 1;
  }

While curly braces for function definitions should rest on a new line
they should not add an indentation level:

  /* valid */
  static void
  my_function (int argument)
  {
    do_my_things ();
  }

  /* invalid */
  static void
  my_function (int argument) {
    do_my_things ();
  }

  /* invalid */
  static void
  my_function (int argument)
    {
      do_my_things ();
    }

Curly braces must not be placed on the same line as a condition:

  /* invalid */
  if (condition) {
    statement_1 ();
    statement_2 ();
  }
+ Conditions

Do not check boolean values for equality:

  /* invalid */
  if (condition == TRUE)
    do_foo ();

  /* valid */
  if (another_condition)
    do_bar ();

Even if C handles NULL equality like a boolean, be explicit:

  /* valid */
  if (some_pointer == NULL)
    do_blah ();

  /* invalid */
  if (some_other_pointer)
    do_blurp ();

In case of conditions split over multiple lines, the logical operators should
always go at the end of the line:

  /* invalid */
  if (condition1
      || condition2
      || condition3)
    {
      do_foo ();
    }

  /* valid */
  if (condition1 &&
      condition2 &&
      (condition3 || (condition4 && condition5)))
    {
      do_blah ();
    }

+ Functions

Functions should be declared by placing the returned value on a separate
line from the function name:

  void
  my_function (void)
  {
  }

The arguments list must be broken into a new line for each argument,
with the argument names right aligned, taking into account pointers:

  void
  my_function (some_type_t     type,
               another_type_t *a_pointer,
               final_type_t    another_type)
  {
  }

The alignment also holds when invoking a function without breaking the
80 characters limit:

  align_function_arguments (first_argument,
                            second_argument,
                            third_argument);

To respect the 80 characters limit do not break the function name from
the arguments:

  /* invalid */
  a_very_long_function_name_with_long_parameters
    (argument_the_first, argument_the_second);

  /* valid */
  first_a = argument_the_first;
  second_a = argument_the_second;
  a_very_long_function_name_with_long_parameters (first_a, second_a);

+ Whitespace

Always put a space before a parenthesis but never after:

  /* valid */
  if (condition)
    do_my_things ();

  /* valid */
  switch (condition)
    {
    }

  /* invalid */
  if(condition)
    do_my_things();

  /* invalid */
  if ( condition )
    do_my_things ( );

A switch() should open a block on a new indentation level, and each case
should start on the same indentation level as the curly braces, with the
case block on a new indentation level:

  /* valid */
  switch (condition)
    {
    case FOO:
      do_foo ();
      break;

    case BAR:
      do_bar ();
      break;
    }

  /* invalid */
  switch (condition) {
    case FOO: do_foo (); break;
    case BAR: do_bar (); break;
  }

  /* invalid */
  switch (condition)
    {
    case FOO: do_foo ();
      break;
    case BAR: do_bar ();
      break;
    }

  /* invalid */
  switch (condition)
    {
      case FOO:
      do_foo ();
      break;
      case BAR:
      do_bar ();
      break;
    }

It is preferable, though not mandatory, to separate the various cases with
a newline:

  switch (condition)
    {
    case FOO:
      do_foo ();
      break;

    case BAR:
      do_bar ();
      break;

    default:
      do_default ();
    }

The 'break' statement for the default: case is not mandatory.

If a case block needs to declare new variables, the same rules as the
inner blocks (see above) apply; the break statement should be placed
outside of the inner block:

  switch (condition)
    {
    case FOO:
      {
        int foo;

        foo = do_foo ();
      }
      break;

    ...
    }

When declaring a structure type use newlines to separate logical sections
of the structure:

  struct _GtkWrapBoxPrivate
  {
    GtkOrientation        orientation;
    GtkWrapAllocationMode mode;

    GtkWrapBoxSpreading   horizontal_spreading;
    GtkWrapBoxSpreading   vertical_spreading;

    guint16               vertical_spacing;
    guint16               horizontal_spacing;

    guint16               minimum_line_children;
    guint16               natural_line_children;

    GList                *children;
  };


Do not eliminate whitespace and newlines just because something would
fit on 80 characters:

  /* invalid */
  if (condition) foo (); else bar ();

Do eliminate trailing whitespace on any line, preferably as a separate
patch or commit. Never use empty lines at the beginning or at the end of
a file.

Do enable the default git pre-commit hook that detect trailing
whitespace for you and help you to avoid corrupting GTK+'s tree with
it. Do that as follows:

  chmod a+x .git/hooks/pre-commit

You might also find the git-stripspace utility helpful which acts as a
filter to remove trailing whitespace as well as initial, final, and
duplicate blank lines.

+ Headers

Headers are special, for GTK+, in that they don't have to obey the
80 characters limit. The only major rule for headers is that the function
definitions should be vertically aligned in three columns:

  return value          function_name           (type   argument,
                                                 type   argument,
                                                 type   argument);

The maximum width of each column is given by the longest element in the
column:

424 425 426 427
  void         gtk_type_set_property (GtkType      *type,
                                      const gchar  *value,
                                      GError      **error);
  const gchar *gtk_type_get_property (GtkType      *type);
428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501

It is also possible to align the columns to the next tab:

  void          gtk_type_set_prop           (GtkType *type,
                                             gfloat   value);
  gfloat        gtk_type_get_prop           (GtkType *type);
  gint          gtk_type_update_foobar      (GtkType *type);

Public headers should never be included directly:

  #if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
  #error "Only <gtk/gtk.h> can be included directly."
  #endif

All headers should have inclusion guards (for internal usage)
and C++ guards:

  #ifndef __GTK_FOO_H__
  #define __GTK_FOO_H__

  #include <gtk/gtk-bar.h>

  G_BEGIN_DECLS

  ...

  G_END_DECLS

  #endif /* __GTK_FOO_H__ */

+ Includes

GTK+ source files should never include the global gtk.h header, but
instead include the individual headers that are needed. Every file must
include config.h first, then its own header, then other GTK+ headers
that it needs, then system and third-party headers that it needs.

  /* valid */
  #include "config.h"

  #include "gtkfoo.h"

  #include "gtkwidget.h"
  #include "gtkbutton.h"

  ...

  #include <string.h>


+ GObject

GObject classes definition and implementation require some additional
coding style notices.

Typedef declarations should be placed at the beginning of the file:

  typedef struct _GtkFoo          GtkFoo;
  typedef struct _GtkFooClass     GtkFooClass;
  typedef struct _GtkFooPrivate   GtkFooPrivate;

This includes enumeration types:

  typedef enum
  {
    GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT,
    GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH
  } GtkSizeRequestMode;

And callback types:

  typedef void (* GtkCallback) (GtkWidget *widget,
                                gpointer   user_data);

502 503 504
Instance structures should only contain the parent type, and optionally a
pointer to a private data structure, and they should be annotated as
"private" using the gtk-doc trigraph:
505 506 507 508 509 510 511 512 513

  struct _GtkFoo
  {
    /*< private >*/
    GtkWidget parent_instance;

    GtkFooPrivate *priv;
  };

514 515 516 517 518 519 520 521 522
The private data pointer is optional and should be omitted in newly
written classes.

Always use the G_DEFINE_TYPE(), G_DEFINE_TYPE_WITH_PRIVATE(), and
G_DEFINE_TYPE_WITH_CODE() macros, or their abstract variants
G_DEFINE_ABSTRACT_TYPE(), G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE(), and
G_DEFINE_ABSTRACT_TYPE_WITH_CODE(); also, use the similar macros for
defining interfaces and boxed types.

523 524 525 526 527
All the properties should be stored inside the private data structure, which
is defined inside the source file - or, if needed, inside a private header
file; the private header filename must end with "private.h" and must not be
installed.

528 529 530
The private data structure should only be accessed internally either using the
pointer inside the instance structure, if one is available, or the generated
instance private data getter function for your type. You should never use the
531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641
G_TYPE_INSTANCE_GET_PRIVATE() macro or the g_type_instance_get_private()
function.

Interface types should always have the dummy typedef for cast purposes:

        typedef struct _GtkFoo              GtkFoo;

The interface structure should have "Interface" postfixed to the dummy typedef:

        typedef struct _GtkFooInterface         GtkFooInterface;

Interfaces must have the following macros:

        - Macro:                                - Expands to:
        • GTK_TYPE_<iface_name>             <iface_name>_get_type
        • GTK_<iface_name>                  G_TYPE_CHECK_INSTANCE_CAST
        • GTK_IS_<iface_name>               G_TYPE_CHECK_INSTANCE_TYPE
        • GTK_<iface_name>_GET_IFACE        G_TYPE_INSTANCE_GET_INTERFACE

+ Memory allocation

When dynamically allocating data on the heap either use g_new() or,
if allocating multiple small data structures, g_slice_new().

Public structure types should always be returned after being zero-ed,
either explicitly for each member, or by using g_new0() or g_slice_new0().

+ Macros

Try to avoid private macros unless strictly necessary. Remember to #undef
them at the end of a block or a series of functions needing them.

Inline functions are usually preferable to private macros.

Public macros should not be used unless they evaluate to a constant.

+ Public API

Avoid exporting variables as public API, since this is cumbersome on some
platforms. It is always preferable to add getters and setters instead.

All public functions must be listed in the gtk.symbols file.

+ Private API

Non-exported functions that are needed in more than one source file
should be named "_gtk_...", and declared in a private header file.

Underscore-prefixed functions are never exported.

Non-exported functions that are only needed in one source file
should be declared static.

+ Documentation

All public APIs must have gtk-doc comments. For functions, these should
be placed in the source file, directly above the function.

  /* valid */
  /**
   * gtk_get_flow:
   * @widget: a #GtkWidget
   *
   * Gets the flow of a widget.
   *
   * Note that flows may be laminar or turbulent...
   *
   * Returns: (transfer none): the flow of @widget
   */
  GtkFlow *
  gtk_get_flow (GtkWidget *widget)
  {

    ...

  }

Doc comments for macros, function types, class structs, etc should be
placed next to the definitions, typically in headers.

Section introductions should be placed in the source file they describe,
after the license header:

  /* valid */
  /**
   * SECTION:gtksizerequest
   * @Short_Description: Height-for-width geometry management
   * @Title: GtkSizeRequest
   *
   * The GtkSizeRequest interface is GTK+'s height-for-width (and
   * width-for-height) geometry management system.
   * ...
   */

To properly document a new function, macro, function type or struct,
it needs to be listed in the gtk3-sections.txt file.

To properly document a new class, it needs to be given its own section
in gtk3-sections.txt, needs to be included in gtk-docs.sgml, and the
get_type function needs to listed in gtk3.types.

+ Old code

New code that is being added to GTK+ should adhere to the style
explained above. Existing GTK+ code does largely follow these
conventions, but there are some differences, e.g. occurrences
of tabs, etc.

It is ok to update the style of a code block or function when you
are touching it anyway, but sweeping whitespace changes obscure the
git history and should be avoided.