Coding Style Release v0.1.0-dev Charlie WONG Apr 24, 2019 Contents 1 C 1 1.1 Header..................................................1 1.2 Scoping..................................................4 1.3 Functions.................................................5 1.4 Features..................................................5 1.5 Naming.................................................. 10 1.6 Comments................................................ 14 1.7 Formatting................................................ 19 2 C++ 35 2.1 Background................................................ 35 2.2 C++ Version............................................... 35 2.3 Header.................................................. 36 2.4 Scoping.................................................. 37 2.5 Class................................................... 40 2.6 Functions................................................. 45 2.7 Features.................................................. 48 2.8 Naming.................................................. 55 2.9 Comments................................................ 57 2.10 Formatting................................................ 58 3 Lua 61 3.1 Types................................................... 61 3.2 Tables................................................... 62 3.3 Strings.................................................. 63 3.4 Functions................................................. 63 3.5 Properties................................................. 64 3.6 Variables................................................. 65 3.7 Conditional Expressions & Equality................................... 66 3.8 Blocks.................................................. 67 3.9 Whitespace................................................ 68 3.10 Commas................................................. 69 3.11 Semicolons................................................ 70 3.12 Type Casting & Coercion........................................ 70 3.13 Naming Conventions........................................... 71 3.14 Modules................................................. 72 3.15 Project Structure............................................. 72 i 3.16 Testing.................................................. 73 4 Shell 75 4.1 Background................................................ 75 4.2 stdout VS stderr............................................. 76 4.3 Comments................................................ 77 4.4 Formatting................................................ 78 4.5 Features.................................................. 83 4.6 Naming.................................................. 87 4.7 Calling Cmds............................................... 89 4.8 Best Practice............................................... 90 4.9 Extra Docs................................................ 92 5 Git 93 5.1 Branches................................................. 93 5.2 Commits................................................. 94 5.3 Messages................................................. 94 5.4 Merging................................................. 95 5.5 Misc................................................... 96 6 Change Log 97 6.1 What is changelog?............................................ 97 6.2 Why keep changelog?.......................................... 97 6.3 Who needs changelog?.......................................... 97 6.4 What may changelog file be named?................................... 97 6.5 What makes good changelog?...................................... 97 6.6 How to minimize the effort to maintain changelog?........................... 98 7 Coding Practices 99 7.1 API.................................................... 99 7.2 Layer................................................... 99 7.3 Integers.................................................. 99 7.4 Expressions................................................ 100 7.5 Floating Point.............................................. 100 7.6 Characters and Strings.......................................... 100 7.7 Memory Management.......................................... 101 7.8 Miscellaneous.............................................. 101 7.9 More Coding Tips............................................ 102 8 Naming Practices 103 9 Exceptions 105 10 Reference 107 ii CHAPTER 1 C 1.1 Header • All header files should be self-contained (compile on their own) and end in .h. • Non-header files meant for inclusion should end in .inc and be used sparingly. All header files should have Header Guard and include all other header files it needs. Prefer placing the definition of inline functions in the same file as their declarations. The definitions of these functions must be included into every .c file that uses them. 1.1.1 Header Guard All header files should have #define guards to prevent multiple inclusion. The format of the symbol name should be <PROJECT>_<PATH>_<FILE>_H. The #define guards should be uniqueness, based on the full path of the project source tree. For example, the file bar/baz.h in the project named foo should have the following guard: /// @file /// file description #ifndef FOO_BAR_BAZ_H #define FOO_BAR_BAZ_H ... #endif // FOO_BAR_BAZ_H 1.1.2 Forward Declarations Avoid using forward declarations where possible. Just #include all the headers you need. Pros 1 Coding Style, Release v0.1.0-dev • Save compile time, as #include force compiler to open and process more files. • Save on unnecessary recompilation, as #include can force code to be recompiled more often, due to unrelated changes in the header. Cons • Hide dependency, can skip necessary recompilation when headers change. • May be broken by subsequent changes to the library, like the header owners making otherwise-compatible changes to the APIs. Decision • Try to avoid forward declarations of entities defined in another project. • When using function declaration in header file, always #include that header. • static functions in .c should well ordered, thus no need of forward declarations. See Includes Order for rules about when and where to #include a header. 1.1.3 Includes Order Use standard order for readability and to avoid hidden dependencies. All project headers should be listed as descen- dants of project source tree without use of UNIX directory shortcuts: . or .. • Related headers • A-BLANK-LINE • C system headers • A-BLANK-LINE • C++ system headers • A-BLANK-LINE • Libraries headers • A-BLANK-LINE • Project headers Note • Any adjacent blank lines should be collapsed for readability. • Within each section the includes should be ordered alphabetically. For example, the file foo/bar/baz.h in project foo should be included into bar/baz.c as following: #include "bar/baz.h" #include <system/headers.h> #include "local/deps/header.h" #include "project/other/header.h" Thus, if bar/baz.h omits any necessary includes, build of bar/baz.c will break up as soon as possible with showing related error message in bar/baz.h. 2 Chapter 1. C Coding Style, Release v0.1.0-dev Sometimes, system-specific code needs conditional includes. Such code can put conditional includes after other includes. Of course, keep the system-specific code small, for example: #include "bar/baz.h" #include "local/header.h" #ifdef UNIX #include <unistd.h> #endif 1.1.4 Inline Functions Define functions inline only when they are small, say, 10 lines or fewer. Should declare functions in a way that allows the compiler to expand them inline rather than calling them through the usual function call mechanism. Pros • Inlining a function can generate more efficient code, as long as the inlined function is small. • Feel free to inline accessors and mutators, and other short, performance-critical functions. Cons • Overuse of inlining can actually make programs slower. • Depending on the function size, it can cause the code size to increase or decrease. • Inlining a very small function will usually decrease the code size, while inlining a very large one can dramatically increase the code size. • For modern processors, smaller code usually runs faster due to better use of the instruction cache. Decision • Usually recursive functions should not be inline. • Macros for small functions are ok if it make sense. • Use inlines function instead of macros where possible. • The thumb rule is do not inline if more than 10 lines long. Tip: • It is typically not cost effective to inline functions with loops or switch statements. • It is important to know that functions are not always inlined even if declared as such. 1.1.5 Header Constants Do not use macros to define constants in header files whenever possible. In general enum are preferred to #define as enums are understood by the debugger. Macro constants in header files can not be used by unit tests. However, you are allowed to define a macro that holds the same value as a non-enum constant, if the value of the constant represents the size of an array. Be aware enums are not of a guaranteed size. So if you have a type that can take a known range of values and it is transported in a message you can not use an enum as the type. Use the correct integer size and use constants or #define. Casting between integers and enums is very error prone as you could cast a value not in the enum. 1.1. Header 3 Coding Style, Release v0.1.0-dev 1.2 Scoping Use of internal linkage in .c files is encouraged for all code that does not need to be referenced elsewhere, and do not use internal linkage in .h files. Functions and variables can be given internal linkage by declaring them static. This means that