1 | Coding Standard rev. 0 (First Draft)␊ |
2 | ␊ |
3 | 1. Indentation␊ |
4 | having seen most indentation styles going from 2 to 8 spaces, I would suggest a indentation of 4 spaces.␊ |
5 | ␊ |
6 | 2. Comments␊ |
7 | I see here two main differents cases:␊ |
8 | function description comments and one-line code quite comments␊ |
9 | ␊ |
10 | For functions documentation, I suggest to use this syntax␊ |
11 | /**␊ |
12 | *␊ |
13 | */␊ |
14 | Note the use of /** that will make future html auto-documentation easier (i.e: Doxygen at least recognize this marker)␊ |
15 | ␊ |
16 | for punctual, short code comment, let's use:␊ |
17 | //␊ |
18 | 3) #define at top of document ␊ |
19 | 4) Global vars right below #include / #define (notation: gLobal)␊ |
20 | Note that global vars and static vars should be avoided as much as possible in favor of local variables use, get/set functions (properties).␊ |
21 | ␊ |
22 | 5) No curly brackets for single lines␊ |
23 | ␊ |
24 | 6) else␊ |
25 | {␊ |
26 | ....␊ |
27 | }␊ |
28 | ␊ |
29 | instead of:␊ |
30 | ␊ |
31 | else {␊ |
32 | ....␊ |
33 | }␊ |
34 | ␊ |
35 | 7) if ␊ |
36 | {␊ |
37 | ....␊ |
38 | }␊ |
39 | instead of:␊ |
40 | ␊ |
41 | if {␊ |
42 | ....␊ |
43 | }␊ |
44 | ␊ |
45 | 8) fall through code (using indention) or bail out early (using returns)?␊ |
46 | Using early bail out for preconditions early in the function code,␊ |
47 | use common sense to avoid as an example more than 4 imbricated if() constructions.␊ |
48 | In the later case, consider decomposing your function in more manageable primitives.␊ |
49 | ␊ |
50 | 9) Spaces/readability i.e. not: if (fd<0)␊ |
51 | but: if (fd < 0)␊ |
52 | ␊ |
53 | 10. types, variables, functions, naming␊ |
54 | non const variables should follow the (currently mostly used) CamelCase convention:␊ |
55 | int myVariableIsFine;␊ |
56 | instead of :␊ |
57 | int my_variable_is_ok;␊ |
58 | ␊ |
59 | Functions should follow the same conventions except for standard c lib related functions.␊ |
60 | Types should share the same convention but start with a Captial letter instead of lower case.␊ |
61 | ␊ |
62 | 11. Please make sure you extensively initialize variables:␊ |
63 | avoid as much as possible:␊ |
64 | int myVar␊ |
65 | ...␊ |
66 | myVar = 10;␊ |
67 | ␊ |
68 | but use instead:␊ |
69 | int myVar = 10;␊ |
70 | ␊ |
71 | 12. const values:␊ |
72 | const int MY_CONST_VARIABLE=42; is also ok for me, depending on the context of use.␊ |
73 | or␊ |
74 | const int MyConstVariable = 42; (with a Capital first letter)␊ |
75 | ␊ |
76 | 13. macro definitions should follow this convention:␊ |
77 | #define MY_HANDY_MACROS_PSEUDO_FUNC() ...␊ |
78 | ␊ |
79 | 14. Macros use should be limited to really special cases where they bring real value (like special optimization cases)␊ |
80 | Most of the time inlining a function is much better than the use of macros␊ |
81 | ␊ |
82 | 15. Don't optimize your code blindly, always favor readability when in doubt.␊ |
83 | Very often, optimization is not necessary where you think it is, think about the bubble sort algorithm, where people would code it in assembly, where a heap or quick sort algorithm would be much more efficient (n log(n) instead of quadratic complexity), as an example when values count to be sorted get high.␊ |
84 | |