4
This document is intended to be a short description of the preferred
5
coding style to be used for the Clutter source code.
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.
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.
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.
20
When in doubt, check the surrounding code and try to imitate it.
24
The maximum line width 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, Clutter 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.
57
Curly braces should not be used for single statement blocks:
62
another_single_statement (arg1);
64
In case of multiple statements, curly braces should be put on another
74
If the condition or the arguments of the single statement need to be
75
split on multiple lines, like:
78
(condition_2 || condition_3))
84
another_single_statement (very_long_argument_1,
90
In general, new blocks should be placed on a new indentation level,
100
gboolean res = FALSE;
102
res = statement_3 (var1);
104
retval = res == TRUE ? -1 : 1;
107
While curly braces for function definitions should rest on a new line
108
they should not add an indentation level:
112
my_function (int argument)
119
my_function (int argument) {
125
my_function (int argument)
130
Curly braces must not be placed on the same line as a condition:
139
Functions should be declared by placing the returned value on a separate
140
line from the function name:
147
The arguments list must be broken into a new line for each argument,
148
with the argument names right aligned, taking into account pointers:
151
my_function (some_type_t type,
152
another_type_t *a_pointer,
153
final_type_t another_type)
157
The alignment also holds when invoking a function without breaking the
160
align_function_arguments (first_argument,
164
To respect the 80 characters limit do not break the function name from
168
a_very_long_function_name_with_long_parameters
169
(argument_the_first, argument_the_second);
172
first_a = argument_the_first;
173
second_a = argument_the_second;
174
a_very_long_function_name_with_long_parameters (first_a, second_a);
178
Always put a space before a parenthesis but never after:
197
A switch() should open a block on a new indentation level, and each case
198
should start on the same indentation level as the curly braces, with the
199
case block on a new indentation level:
215
case FOO: do_foo (); break;
216
case BAR: do_bar (); break;
219
If a case block needs to declare new variables, the same rules as the
220
inner blocks (see above) apply; the break statement should be placed
221
outside of the inner block:
236
When declaring a structure type use newlines to separate logical sections
239
struct _ClutterActorPrivate
245
ClutterRequestMode request_mode;
247
/* requisition sizes */
248
ClutterUnit request_width_for_height;
249
ClutterUnit request_min_width;
250
ClutterUnit request_natural_width;
251
ClutterUnit request_height_for_width;
252
ClutterUnit request_min_height;
253
ClutterUnit request_natural_height;
255
ClutterActorBox allocation;
260
Do not eliminate whitespace and newlines just because something would
261
fit on 80 characters:
264
if (condition) foo (); else bar ();
266
Do eliminate trailing whitespace on any line, preferably as a separate
267
patch or commit. Never use empty lines at the beginning or at the end of
270
Do enable the default git pre-commit hook that detect trailing
271
whitespace for you and help you to avoid corrupting Clutter's tree with
272
it. Do that as follows:
274
chmod a+x .git/hooks/pre-commit
276
You might also find the git-stripspace utility helpful which acts as a
277
filter to remove trailing whitespace as well as initial, final, and
278
duplicate blank lines.
282
Headers are special, for Clutter, in that they don't have to obey the
283
80 characters limit. The only major rule for headers is that the functions
284
definition should be vertically aligned in three columns:
286
return value function_name (type argument,
290
The maximum width of each column is given by the longest element in the
293
void clutter_type_set_property (ClutterType *type,
296
G_CONST_RETURN gchar *clutter_type_get_property (ClutterType *type);
298
Public headers should never be included directly:
300
#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
301
#error "Only <clutter/clutter.h> can be included directly."
304
Public headers should also have inclusion guards (for internal usage)
307
#ifndef __CLUTTER_HEADER_H__
308
#define __CLUTTER_HEADER_H__
310
#include <clutter/clutter-actor.h>
318
#endif /* __CLUTTER_HEADER_H__ */
322
GObject classes definition and implementation require some additional
323
coding style notices.
325
Typedef declarations should be places at the beginning of the file:
327
typedef struct _ClutterActor ClutterActor;
328
typedef struct _ClutterActorPrivate ClutterActorPrivate;
329
typedef struct _ClutterActorClass ClutterActorClass;
331
This includes enumeration types:
335
CLUTTER_REQUEST_WIDTH_FOR_HEIGHT,
336
CLUTTER_REQUEST_HEIGHT_FOR_WIDTH
337
} ClutterRequestMode;
341
typedef void (* ClutterCallback) (ClutterActor *actor,
344
Instance structures should only contain the parent type and a pointer to a
345
private data structure:
347
struct _ClutterRectangle
349
ClutterActor parent_instance;
351
ClutterRectanglePrivate *priv;
354
All the properties should be stored inside the private data structure, which
355
is defined inside the source file.
357
The private data structure should only be accessed internally using the
358
pointer inside the instance structure, and never using the
359
G_TYPE_INSTANCE_GET_PRIVATE() macro or the g_type_instance_get_private()
362
Always use the G_DEFINE_TYPE(), G_DEFINE_TYPE_WITH_CODE() macros, or
363
their abstract variants G_DEFINE_ABSTRACT_TYPE() and
364
G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
368
When dynamically allocating data on the heap either use g_new() or,
369
if allocating multiple small data structures, g_slice_new().
371
Public structure types should always be returned after being zero-ed,
372
either explicitly, or by using g_new0() or g_slice_new0().
376
Try to avoid macros unless strictly necessary. Remember to #undef them
377
at the end of a block or a series of functions needing them.
379
Inline functions are usually preferable to macros.
added
removed
CODING_STYLE
