2 -------------------------------------------------------------------------------
4 This document is intended to be a short description of the preferred
5 coding style to be used for the GTK+ source code. It was strongly
6 inspired by Clutter's CODING_STYLE.
8 Coding style is a matter of consistency, readability and maintainance;
9 coding style is also completely arbitrary and a matter of taste. This
10 document will use examples at the very least to provide authoritative
11 and consistent answers to common questions regarding the coding style,
12 and will also try to identify the allowed exceptions.
14 The examples will show the preferred coding style; the negative examples
15 will be clearly identified. Please, don't submit code to GTK+ that
16 looks like any of these.
18 Part of the rationales for these coding style rules are available either
19 in the kernel CodingStyle document or in Cairo's CODING_STYLE one.
21 When in doubt, check the surrounding code and try to imitate it.
25 The maximum line width for source files is 80 characters, whenever possible.
26 Longer lines are usually an indication that you either need a function
27 or a pre-processor macro.
31 Each new level is indented 2 or more spaces than the previous level:
36 This can only be achieved using space characters. It may not be achieved
37 using tab characters alone, or using a combination of spaces and tabs.
39 Do not change the editor's configuration to change the meaning of a
40 tab character (see below); code using tabs to indent will not be accepted
43 Even if two spaces for each indentation level allows deeper nesting than
44 8 spaces, GTK+ favours self-documenting function names that can take
45 quite some space. For this reason you should avoid deeply nested code.
49 The tab character must always be expanded to spaces. If a literal
50 tab must be used inside the source, the tab must always be interpreted
51 according to its traditional meaning:
53 Advance to the next column which is a multiple of 8.
54 [ these two lines should be aligned ]
58 Curly braces should not be used for single statement blocks:
63 another_single_statement (arg1);
65 In case of multiple statements, curly braces should be put on another
75 The "no block for single statements" rule has only four exceptions:
77 ① if the single statement covers multiple lines, e.g. for functions with
78 many arguments, and it is followed by else or else if:
83 a_single_statement_with_many_arguments (some_lengthy_argument,
84 another_lengthy_argument,
89 another_single_statement (arg1, arg2);
91 ② if the condition is composed of many lines:
95 (condition2 && condition3) ||
97 (condition5 && (condition6 || condition7)))
99 a_single_statement ();
102 ③ Nested if's, in which case the block should be placed on the
108 if (another_condition)
111 another_single_statement ();
116 if (another_condition)
118 else if (yet_another_condition)
119 another_single_statement ();
121 ④ If either side of an if-else statement has braces, both sides
122 should, to match up indentation:
144 In general, new blocks should be placed on a new indentation level,
154 gboolean res = FALSE;
156 res = statement_3 (var1);
158 retval = res ? -1 : 1;
161 While curly braces for function definitions should rest on a new line
162 they should not add an indentation level:
166 my_function (int argument)
173 my_function (int argument) {
179 my_function (int argument)
184 Curly braces must not be placed on the same line as a condition:
193 Do not check boolean values for equality:
196 if (condition == TRUE)
200 if (another_condition)
203 Even if C handles NULL equality like a boolean, be explicit:
206 if (some_pointer == NULL)
210 if (some_other_pointer)
213 In case of conditions split over multiple lines, the logical operators should
214 always go at the end of the line:
227 (condition3 || (condition4 && condition5)))
234 Functions should be declared by placing the returned value on a separate
235 line from the function name:
242 The arguments list must be broken into a new line for each argument,
243 with the argument names right aligned, taking into account pointers:
246 my_function (some_type_t type,
247 another_type_t *a_pointer,
248 final_type_t another_type)
252 The alignment also holds when invoking a function without breaking the
255 align_function_arguments (first_argument,
259 To respect the 80 characters limit do not break the function name from
263 a_very_long_function_name_with_long_parameters
264 (argument_the_first, argument_the_second);
267 first_a = argument_the_first;
268 second_a = argument_the_second;
269 a_very_long_function_name_with_long_parameters (first_a, second_a);
273 Always put a space before a parenthesis but never after:
292 A switch() should open a block on a new indentation level, and each case
293 should start on the same indentation level as the curly braces, with the
294 case block on a new indentation level:
310 case FOO: do_foo (); break;
311 case BAR: do_bar (); break;
334 It is preferable, though not mandatory, to separate the various cases with
351 The 'break' statement for the default: case is not mandatory.
353 If a case block needs to declare new variables, the same rules as the
354 inner blocks (see above) apply; the break statement should be placed
355 outside of the inner block:
370 When declaring a structure type use newlines to separate logical sections
373 struct _GtkWrapBoxPrivate
375 GtkOrientation orientation;
376 GtkWrapAllocationMode mode;
378 GtkWrapBoxSpreading horizontal_spreading;
379 GtkWrapBoxSpreading vertical_spreading;
381 guint16 vertical_spacing;
382 guint16 horizontal_spacing;
384 guint16 minimum_line_children;
385 guint16 natural_line_children;
391 Do not eliminate whitespace and newlines just because something would
392 fit on 80 characters:
395 if (condition) foo (); else bar ();
397 Do eliminate trailing whitespace on any line, preferably as a separate
398 patch or commit. Never use empty lines at the beginning or at the end of
401 Do enable the default git pre-commit hook that detect trailing
402 whitespace for you and help you to avoid corrupting GTK+'s tree with
403 it. Do that as follows:
405 chmod a+x .git/hooks/pre-commit
407 You might also find the git-stripspace utility helpful which acts as a
408 filter to remove trailing whitespace as well as initial, final, and
409 duplicate blank lines.
413 Headers are special, for GTK+, in that they don't have to obey the
414 80 characters limit. The only major rule for headers is that the function
415 definitions should be vertically aligned in three columns:
417 return value function_name (type argument,
421 The maximum width of each column is given by the longest element in the
424 void gtk_type_set_property (GtkType *type,
427 const gchar *gtk_type_get_property (GtkType *type);
429 It is also possible to align the columns to the next tab:
431 void gtk_type_set_prop (GtkType *type,
433 gfloat gtk_type_get_prop (GtkType *type);
434 gint gtk_type_update_foobar (GtkType *type);
436 Public headers should never be included directly:
438 #if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
439 #error "Only <gtk/gtk.h> can be included directly."
442 All headers should have inclusion guards (for internal usage)
445 #ifndef __GTK_FOO_H__
446 #define __GTK_FOO_H__
448 #include <gtk/gtk-bar.h>
456 #endif /* __GTK_FOO_H__ */
460 GTK+ source files should never include the global gtk.h header, but
461 instead include the individual headers that are needed. Every file must
462 include config.h first, then its own header, then other GTK+ headers
463 that it needs, then system and third-party headers that it needs.
470 #include "gtkwidget.h"
471 #include "gtkbutton.h"
480 GObject classes definition and implementation require some additional
481 coding style notices.
483 Typedef declarations should be placed at the beginning of the file:
485 typedef struct _GtkFoo GtkFoo;
486 typedef struct _GtkFooClass GtkFooClass;
487 typedef struct _GtkFooPrivate GtkFooPrivate;
489 This includes enumeration types:
493 GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT,
494 GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH
495 } GtkSizeRequestMode;
499 typedef void (* GtkCallback) (GtkWidget *widget,
502 Instance structures should only contain the parent type and a pointer to a
503 private data structure, and they should be annotated as "private":
508 GtkWidget parent_instance;
513 All the properties should be stored inside the private data structure, which
514 is defined inside the source file - or, if needed, inside a private header
515 file; the private header filename must end with "private.h" and must not be
518 The private data structure should only be accessed internally using the
519 pointer inside the instance structure, and never using the
520 G_TYPE_INSTANCE_GET_PRIVATE() macro or the g_type_instance_get_private()
523 Always use the G_DEFINE_TYPE(), G_DEFINE_TYPE_WITH_CODE() macros, or
524 their abstract variants G_DEFINE_ABSTRACT_TYPE() and
525 G_DEFINE_ABSTRACT_TYPE_WITH_CODE(), and the similar macros for defining
528 Interface types should always have the dummy typedef for cast purposes:
530 typedef struct _GtkFoo GtkFoo;
532 The interface structure should have "Interface" postfixed to the dummy typedef:
534 typedef struct _GtkFooInterface GtkFooInterface;
536 Interfaces must have the following macros:
538 - Macro: - Expands to:
539 • GTK_TYPE_<iface_name> <iface_name>_get_type
540 • GTK_<iface_name> G_TYPE_CHECK_INSTANCE_CAST
541 • GTK_IS_<iface_name> G_TYPE_CHECK_INSTANCE_TYPE
542 • GTK_<iface_name>_GET_IFACE G_TYPE_INSTANCE_GET_INTERFACE
546 When dynamically allocating data on the heap either use g_new() or,
547 if allocating multiple small data structures, g_slice_new().
549 Public structure types should always be returned after being zero-ed,
550 either explicitly for each member, or by using g_new0() or g_slice_new0().
554 Try to avoid private macros unless strictly necessary. Remember to #undef
555 them at the end of a block or a series of functions needing them.
557 Inline functions are usually preferable to private macros.
559 Public macros should not be used unless they evaluate to a constant.
563 Avoid exporting variables as public API, since this is cumbersome on some
564 platforms. It is always preferable to add getters and setters instead.
566 All public functions must be listed in the gtk.symbols file.
570 Non-exported functions that are needed in more than one source file
571 should be named "_gtk_...", and declared in a private header file.
573 Underscore-prefixed functions are never exported.
575 Non-exported functions that are only needed in one source file
576 should be declared static.
580 All public APIs must have gtk-doc comments. For functions, these should
581 be placed in the source file, directly above the function.
586 * @widget: a #GtkWidget
588 * Gets the flow of a widget.
590 * Note that flows may be laminar or turbulent...
592 * Returns: (transfer none): the flow of @widget
595 gtk_get_flow (GtkWidget *widget)
602 Doc comments for macros, function types, class structs, etc should be
603 placed next to the definitions, typically in headers.
605 Section introductions should be placed in the source file they describe,
606 after the license header:
610 * SECTION:gtksizerequest
611 * @Short_Description: Height-for-width geometry management
612 * @Title: GtkSizeRequest
614 * The GtkSizeRequest interface is GTK+'s height-for-width (and
615 * width-for-height) geometry management system.
619 To properly document a new function, macro, function type or struct,
620 it needs to be listed in the gtk3-sections.txt file.
622 To properly document a new class, it needs to be given its own section
623 in gtk3-sections.txt, needs to be included in gtk-docs.sgml, and the
624 get_type function needs to listed in gtk3.types.
628 New code that is being added to GTK+ should adhere to the style
629 explained above. Existing GTK+ code does largely follow these
630 conventions, but there are some differences, e.g. occurrences
633 It is ok to update the style of a code block or function when you
634 are touching it anyway, but sweeping whitespace changes obscure the
635 git history and should be avoided.