| 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 | |
