1 Every project has its coding style, and oFono is not an exception. This
2 document describes the preferred coding style for oFono code, in order to keep
3 some level of consistency among developers so that code can be easily
4 understood and maintained, and also to help your code survive under
5 maintainer's fastidious eyes so that you can get a passport for your patch
8 First of all, oFono coding style must follow every rule for Linux kernel
9 (http://www.kernel.org/doc/Documentation/CodingStyle). There also exists a tool
10 named checkpatch.pl to help you check the compliance with it. Just type
11 "checkpatch.pl --no-tree patch_name" to check your patch. In theory, you need
12 to clean up all the warnings and errors except this one: "ERROR: Missing
13 Signed-off-by: line(s)". oFono does not used Signed-Off lines, so including
14 them is actually an error. In certain circumstances one can ignore the 80
15 character per line limit. This is generally only allowed if the alternative
16 would make the code even less readable.
18 Besides the kernel coding style above, oFono has special flavors for its own.
19 Some of them are mandatory (marked as 'M'), while some others are optional
20 (marked as 'O'), but generally preferred.
22 M1: Blank line before and after an if/while/do/for statement
23 ============================================================
24 There should be a blank line before if statement unless the if is nested and
25 not preceded by an expression or variable declaration.
52 The only exception to this rule applies when a variable is being allocated:
53 array = g_try_new0(int, 20);
54 if (array == NULL) // Correct
58 M2: Multiple line comment
59 =========================
60 If your comments have more then one line, please start it from the second line.
64 * first line comment // correct
70 M3: Space before and after operator
71 ===================================
72 There should be a space before and after each operator.
80 If your condition in if, while, for statement or a function declaration is too
81 long to fit in one line, the new line needs to be indented not aligned with the
86 if (call->status == CALL_STATUS_ACTIVE ||
87 call->status == CALL_STATUS_HELD) { // wrong
88 ofono_dbus_dict_append();
91 if (call->status == CALL_STATUS_ACTIVE ||
92 call->status == CALL_STATUS_HELD) { // correct
93 ofono_dbus_dict_append();
96 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
97 num sim_ust_service index) // wrong
104 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
105 enum sim_ust_service index) // correct
111 If the line being wrapped is a function call or function declaration, the
112 preferred style is to indent at least past the opening parenthesis. Indenting
113 further is acceptable as well (as long as you don't hit the 80 character
116 If this is not possible due to hitting the 80 character limit, then indenting
117 as far as possible to the right without hitting the limit is preferred.
122 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
123 enum sim_ust_service index); // worse
126 gboolean sim_ust_is_available(unsigned char *service_ust, unsigned char len,
127 enum sim_ust_service index);
130 M5: Git commit message 50/72 formatting
131 =======================================
132 The commit message header should be within 50 characters. And if you have
133 detailed explanatory text, wrap it to 72 character.
136 M6: Space when doing type casting
137 =================================
138 There should be a space between new type and variable.
142 a = (int *)b; // wrong
144 a = (int *) b; // correct
147 M7: Don't initialize variable unnecessarily
148 ===========================================
149 When declaring a variable, try not to initialize it unless necessary.
154 for (i = 0; i < 3; i++) {
158 M8: Use g_try_malloc instead of g_malloc
159 ========================================
160 When g_malloc fails, the whole program would exit. Most of time, this is not
161 the expected behavior, and you may want to use g_try_malloc instead.
164 additional = g_try_malloc(len - 1); // correct
165 if (additional == NULL)
169 M9: Follow the order of include header elements
170 ===============================================
171 When writing an include header the various elements should be in the following
174 - forward declarations
178 - function declarations and inline function definitions
181 M10: Internal headers must not use include guards
182 =================================================
183 Any time when creating a new header file with non-public API, that header
184 must not contain include guards.
190 Enums must have a descriptive name. The enum type should be small caps and
191 it should not be typedef-ed. Enum contents should be in CAPITAL letters and
192 prefixed by the enum type name.
197 ANIMAL_TYPE_FOUR_LEGS,
198 ANIMAL_TYPE_EIGHT_LEGS,
199 ANIMAL_TYPE_TWO_LEGS,
202 If the enum contents have values (e.g. from specification) the formatting
203 should be as follows:
206 ANIMAL_TYPE_FOUR_LEGS = 4,
207 ANIMAL_TYPE_EIGHT_LEGS = 8,
208 ANIMAL_TYPE_TWO_LEGS = 2,
211 M12: Enum as switch variable
214 If the variable of a switch is an enum, you must not include a default in
215 switch body. The reason for this is: If later on you modify the enum by adding
216 a new type, and forget to change the switch accordingly, the compiler will
217 complain the new added type hasn't been handled.
222 ANIMAL_TYPE_FOUR_LEGS = 4,
223 ANIMAL_TYPE_EIGHT_LEGS = 8,
224 ANIMAL_TYPE_TWO_LEGS = 2,
230 case ANIMAL_TYPE_FOUR_LEGS:
233 case ANIMAL_TYPE_EIGHT_LEGS:
236 case ANIMAL_TYPE_TWO_LEGS:
243 However if the enum comes from an external header file outside ofono
244 we cannot make any assumption of how the enum is defined and this
245 rule might not apply.
247 M13: Check for pointer being NULL
248 =================================
250 When checking if a pointer or a return value is NULL, explicitly compare to
251 NULL rather than use the shorter check with "!" operator.
255 array = g_try_new0(int, 20);
260 if (!g_at_chat_get_slave(chat)) // Wrong
264 array = g_try_new0(int, 20);
265 if (array == NULL) // Correct
269 M14: Always use parenthesis with sizeof
270 =======================================
271 The expression argument to the sizeof operator should always be in
276 memset(stuff, 0, sizeof(*stuff));
279 memset(stuff, 0, sizeof *stuff); // Wrong
282 M15: Use void if function has no parameters
283 ===========================================================
284 A function with no parameters must use void in the parameter list.
297 M16: Don't use hex value with shift operators
298 ==============================================
299 The expression argument to the shift operators should not be in hex.
311 Better to use abbreviation, rather than full name, to name a variable,
312 function, struct, etc.
315 supplementary_service // too long
319 O2: Try to avoid complex if body
320 ================================
321 It's better not to have a complicated statement for if. You may judge its
322 contrary condition and return | break | continue | goto ASAP.
328 call = synthesize_outgoing_call(vc, vc->pending);
329 v = voicecall_create(vc, call);
330 v->detect_time = time(NULL);
331 DBG("Registering new call: %d", call->id);
332 voicecall_dbus_register(v);
341 call = synthesize_outgoing_call(vc, vc->pending);
342 v = voicecall_create(vc, call);
343 v->detect_time = time(NULL);
344 DBG("Registering new call: %d", call->id);
345 voicecall_dbus_register(v);