CodingStyle
1 2 3 4 Introduction 5 6 Most of this style guide has been copied wholesale from the Linux kernel 7 documents - See linux/Documentation/CodingStyle for the full text. 8 The C++ recommendations have been drawn from various sources such as the 9 GTK headers, "C++ The Complete Reference" by Schildt, and IRC discussions. 10 11 12 Indentation 13 14 Rationale: The whole idea behind indentation is to clearly define where 15 a block of control starts and ends. Especially when you've been looking 16 at your screen for 20 straight hours, you'll find it a lot easier to see 17 how the indentation works if you have large indentations. 18 19 Now, some people will claim that having 8-character indentations makes 20 the code move too far to the right, and makes it hard to read on a 21 80-character terminal screen. Whilst the GNU style of 2-character 22 indentations reduces the clarity. For EMC2, a compromise of 4-character 23 indentation has been chosen. This still spreads the code out and causes 24 lines to wrap round leading to difficulties in reading the sources. The 25 answer to that is that if you need more than 3 levels of indentation, you're 26 screwed anyway, and should fix your program. 27 28 29 Placing Braces 30 31 The other issue that always comes up in C styling is the placement of 32 braces. Unlike the indent size, there are few technical reasons to 33 choose one placement strategy over the other, but the preferred way, as 34 shown to us by the prophets Kernighan and Ritchie, is to put the opening 35 brace last on the line, and put the closing brace first, thusly: 36 37 if (x is true) { 38 we do y 39 } 40 41 However, there is one special case, namely functions: they have the 42 opening brace at the beginning of the next line, thus: 43 44 int function(int x) 45 { 46 body of function 47 } 48 49 Note that the closing brace is empty on a line of its own, _except_ in 50 the cases where it is followed by a continuation of the same statement, 51 i.e. a "while" in a do-statement or an "else" in an if-statement, like 52 this: 53 54 do { 55 body of do-loop 56 } while (condition); 57 58 and 59 60 if (x == y) { 61 .. 62 } else if (x > y) { 63 ... 64 } else { 65 .... 66 } 67 68 Also, note that this brace-placement also minimizes the number of empty 69 (or almost empty) lines, without any loss of readability. Thus, as the 70 supply of new-lines on your screen is not a renewable resource (think 71 25-line terminal screens here), you have more empty lines to put 72 comments on. 73 74 Naming 75 76 C is a Spartan language, and so should your naming be. Unlike Modula-2 77 and Pascal programmers, C programmers do not use cute names like 78 ThisVariableIsATemporaryCounter. A C programmer would call that 79 variable "tmp", which is much easier to write, and not the least more 80 difficult to understand. 81 82 HOWEVER, while mixed-case names are frowned upon, descriptive names for 83 global variables are a must. To call a global function "foo" is a 84 shooting offense. 85 86 GLOBAL variables (to be used only if you _really_ need them) need to 87 have descriptive names, as do global functions. If you have a function 88 that counts the number of active users, you should call that 89 "count_active_users()" or similar, you should _not_ call it "cntusr()". 90 91 Encoding the type of a function into the name (so-called Hungarian 92 notation) is brain damaged - the compiler knows the types anyway and can 93 check those, and it only confuses the programmer. No wonder Microsoft 94 makes buggy programs. 95 96 LOCAL variable names should be short, and to the point. If you have 97 some random integer loop counter, it should probably be called "i". 98 Calling it "loop_counter" is non-productive, if there is no chance of it 99 being mis-understood. Similarly, "tmp" can be just about any type of 100 variable that is used to hold a temporary value. 101 102 If you are afraid to mix up your local variable names, you have another 103 problem, which is called the function-growth-hormone-imbalance syndrome. 104 See next chapter. 105 106 107 Functions 108 109 Functions should be short and sweet, and do just one thing. They should 110 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, 111 as we all know), and do one thing and do that well. 112 113 The maximum length of a function is inversely proportional to the 114 complexity and indentation level of that function. So, if you have a 115 conceptually simple function that is just one long (but simple) 116 case-statement, where you have to do lots of small things for a lot of 117 different cases, it's OK to have a longer function. 118 119 However, if you have a complex function, and you suspect that a 120 less-than-gifted first-year high-school student might not even 121 understand what the function is all about, you should adhere to the 122 maximum limits all the more closely. Use helper functions with 123 descriptive names (you can ask the compiler to in-line them if you think 124 it's performance-critical, and it will probably do a better job of it 125 that you would have done). 126 127 Another measure of the function is the number of local variables. They 128 shouldn't exceed 5-10, or you're doing something wrong. Re-think the 129 function, and split it into smaller pieces. A human brain can 130 generally easily keep track of about 7 different things, anything more 131 and it gets confused. You know you're brilliant, but maybe you'd like 132 to understand what you did 2 weeks from now. 133 134 135 Commenting 136 137 Comments are good, but there is also a danger of over-commenting. NEVER 138 try to explain HOW your code works in a comment: it's much better to 139 write the code so that the _working_ is obvious, and it's a waste of 140 time to explain badly written code. 141 142 Generally, you want your comments to tell WHAT your code does, not HOW. 143 A boxed comment describing the function, return value, and who calls it 144 placed above the body is good. 145 Also, try to avoid putting comments inside a function body: if the 146 function is so complex that you need to separately comment parts of it, 147 you should probably re-read the Functions section again. You can make 148 small comments to note or warn about something particularly clever (or 149 ugly), but try to avoid excess. Instead, put the comments at the head 150 of the function, telling people what it does, and possibly WHY it does 151 it. 152 153 If comments along the lines of /* Fix me */ are used, please, please, say 154 why something needs fixing. When a change has been made to the affected 155 portion of code, either remove the comment, or amend it to indicate a 156 change has been made and needs testing. 157 158 159 Shell Scripts & Makefiles 160 161 Not everyone has the same tools and packages installed. Some people use 162 vi, others emacs - A few even avoid having either package installed, 163 preferring a lightweight text editor such as nano or the one built in to 164 Midnight Commander. 165 166 gawk versus mawk - Again, not everyone will have gawk installed, mawk is 167 nearly a tenth of the size and yet conforms to the Posix AWK standard. If 168 some obscure gawk specific command is needed that mawk does not provide, 169 than the script will break for some users. The same would apply to mawk. 170 In short, use the generic awk invocation in preference to gawk or mawk. 171 172 173 C++ Conventions 174 175 C++ coding styles are always likely to end up in heated debates (a bit like 176 the emacs versus vi arguments). One thing is certain however, a common 177 style used by everyone working on a project leads to uniform and readable code. 178 179 Naming conventions: Constants either from #defines or enumerations should 180 be in upper case through out. Rationale: Makes it easier to spot compile 181 time constants in the source code. 182 e.g. EMC_MESSAGE_TYPE 183 184 Classes and Namespaces should capitalize the first letter of each word and 185 avoid underscores. Rationale: Identifies classes, constructors and destructors. 186 e.g. GtkWidget 187 188 Methods (or function names) should follow the C recommendations above and 189 should not include the class name. Rationale: Maintains a common style across 190 C and C++ sources. 191 e.g. get_foo_bar() 192 193 However, boolean methods are easier to read if they avoid underscores and use 194 an 'is' prefix (not to be confused with methods that manipulate a boolean). 195 Rationale: Identifies the return value as TRUE or FALSE and nothing else. 196 e.g. isOpen, isHomed 197 198 Do NOT use "Not" in a boolean name, it leads only leads to confusion when 199 doing logical tests. 200 e.g. isNotOnLimit or is_not_on_limit are BAD. 201 202 Variable names should avoid the use of upper case and underscores except 203 for local or private names. The use of global variables should be avoided 204 as much as possible. Rationale: Clarifies which are variables and which 205 are methods. Public: 206 e.g. axislimit 207 Private: 208 e.g. maxvelocity_ 209 210 Specific method naming conventions 211 212 The terms get and set should be used where an attribute is accessed directly. 213 Rationale: Indicates the purpose of the function or method. 214 e.g. get_foo set_bar 215 216 For methods involving boolean attributes, set & reset is preferred. Rationale: 217 As above. 218 e.g. set_amp_enable reset_amp_fault 219 220 Math intensive methods should use compute as a prefix. Rationale: Shows that 221 it is computationally intensive and will hog the CPU. 222 e.g. compute_PID 223 224 Abbreviations in names should be avoided where possible - The exception is 225 for local variable names. Rationale: Clarity of code. 226 e.g. pointer is preferred over ptr 227 compute is preferred over cmp compare is again preferred over cmp. 228 229 Enumerates and other constants can be prefixed by a common type name 230 e.g. enum COLOR { 231 COLOR_RED, COLOR_BLUE 232 }; 233 234 Excessive use of macros and defines should be avoided - Using simple methods 235 or functions is preferred. Rationale: Improves the debugging process. 236 237 Include Statements Header files must be included at the top of a source file 238 and not scattered throughout the body. They should be sorted and grouped 239 by their hierarchical position within the system with the low level files 240 included first. Include file paths should NEVER be absolute - Use the 241 compiler -I flag instead. Rationale: Headers may not be in the same place 242 on all systems. 243 244 Pointers and references should have their reference symbol next to the 245 variable name rather than the type name. Rationale: Reduces confusion. 246 e.g. float *x or int &i 247 248 Implicit tests for zero should not be used except for boolean variables. 249 e.g. if (spindle_speed != 0) NOT if (spindle_speed) 250 251 Only loop control statements must be included in a for() construct. 252 e.g. sum = 0; 253 for (i = 0; i < 10; i++) { 254 sum += value[i]; 255 } 256 257 NOT 258 for (i = 0, sum = 0; i < 10; i++) sum += value[i]; 259 260 Likewise, executable statements in conditionals must be avoided. 261 e.g. if (fd = open(file_name) is bad. 262 263 Complex conditional statements should be avoided - Introduce temporary 264 boolean variables instead. 265 266 The form while(true) should be used for infinite loops. 267 e.g. while (true) { 268 ...; 269 } 270 271 NOT 272 273 for (;;) { 274 ...; 275 } 276 277 or 278 279 while (1) { 280 ...; 281 } 282 283 Parentheses should be used in plenty in mathematical expressions - Do not rely 284 on operator precedence when an extra parentheses would clarify things. 285 286 File names: C++ sources and headers use .cc and .hh extension. The use of .c 287 and .h are reserved for plain C. Headers are for class, method, and structure 288 declarations, not code (unless the functions are declared inline).