Changes between Version 21 and Version 22 of Coding_Conventions
- Timestamp:
- May 11, 2013, 8:49:08 AM (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Coding_Conventions
v21 v22 2 2 3 3 == Introduction == 4 5 4 The goal of these coding conventions is to encourage consistency within the code, rather than claiming some particular style is better than any other. As such, the main guideline is: 5 6 6 * When modifying a piece of code, try to follow its existing style. In particular: 7 * Primarily, try to match the style of the functions that you're editing (assuming it's at least self-consistent and not too bizarre), in order to avoid making it less self-consistent.8 * Secondly, try to match the style of the files that you're editing.9 * Then, try to match the style of the other code in the subdirectory you're editing.10 * Finally, try to match the global guidelines discussed on this page.7 * Primarily, try to match the style of the functions that you're editing (assuming it's at least self-consistent and not too bizarre), in order to avoid making it less self-consistent. 8 * Secondly, try to match the style of the files that you're editing. 9 * Then, try to match the style of the other code in the subdirectory you're editing. 10 * Finally, try to match the global guidelines discussed on this page. 11 11 12 12 Our code is currently not entirely consistent in places, but the following guidelines attempt to describe the most common style and are what we should converge towards. (Obviously we always want clean, readable, adequately-documented code - lots of articles and books already talk about how to do that - so here we're mostly describing minor details.) 13 13 14 14 == C++ == 15 16 15 === Creating new files === 17 18 16 * All source files (.cpp, .h) must start with the following GPL license header, before any other content: 19 17 {{{ … … 36 34 */ 37 35 }}} 38 replacing `2013` with the year that the file was last updated.39 40 ''Exception:'' Code in `source/lib/`(and a few other files) should use the MIT license instead:36 replacing `2013` with the year that the file was last updated. 37 38 '' Exception:'' Code in `source/lib/` (and a few other files) should use the MIT license instead: 41 39 {{{ 42 40 #!cpp … … 78 76 79 77 === Formatting === 80 81 78 * Use tabs for indentation, not spaces. 82 79 … … 100 97 } 101 98 }}} 102 ''Exception:'' Code in `source/lib/` omits the space before the '`(`' in statements like "`if(...)`", "`while(...)`", etc.99 ''Exception:'' Code in `source/lib/` omits the space before the '`(`' in statements like "`if(...)`", "`while(...)`", etc. 103 100 104 101 * Try to avoid very wide lines. Typical wrapping points are 80 characters, or 120, or 132, etc. (There's no strict limit - aim for whatever seems most readable.) … … 133 130 134 131 === Error reporting === 135 136 132 * For engine bugs (that is, error cases which need to be fixed by C++ developers, and which should never be triggered by users or modders (even if they write invalid data files)), use "`debug_warn(L"message")`" to report the error. (This pops up an ugly dialog box with stack trace and continue/debug/exit buttons.) 137 133 … … 141 137 LOGERROR(L"Failed to load item %d from file %ls", i, path.c_str()); 142 138 }}} 143 This gets display on screen in red, and saved in the log files. `LOGERROR` takes `wprintf`-style format strings. 144 ''Exception:'' Code in `source/lib/` can't use `LOGERROR` (it can only use things defined in `source/lib/`). 139 This gets display on screen in red, and saved in the log files. `LOGERROR` takes `wprintf`-style format strings. ''Exception:'' Code in `source/lib/` can't use `LOGERROR` (it can only use things defined in `source/lib/`). 145 140 146 141 * The engine should try to cope gracefully with `LOGERROR` cases, e.g. abort loading the current file; it should never crash in those cases. 147 142 148 143 === Documentation === 149 150 144 * Use [http://www.doxygen.org/ Doxygen] comments (explained [http://www.stack.nl/~dimitri/doxygen/docblocks.html here] as !JavaDoc style), e.g. 151 145 {{{ … … 175 169 176 170 === Strings === 177 178 171 * Use `CStr` instead of `std::string`. Use `CStrW` instead of `std::wstring`. (These are subclasses of `std::[w]string` with various extra methods added for convenience.) 179 * ''Exception:'' `source/lib/` and `source/simulation2/` and `source/scriptinterface/` tend to prefer `std::[w]string` instead.180 * `CStr8` is an alias for `CStr`. Prefer to use `CStr`.172 * ''Exception:'' `source/lib/` and `source/simulation2/` and `source/scriptinterface/` tend to prefer `std::[w]string` instead. 173 * `CStr8` is an alias for `CStr`. Prefer to use `CStr`. 181 174 182 175 * Compare strings using `==` (not e.g. "`a.compare(b) == 0`"). Compare to literals directly (e.g. "`someCStrVariable == "foo"`", not "`someCStrVariable == CStr("foo")`"). … … 202 195 203 196 === Misc === 204 205 197 * In header files, avoid `#include` and use forward declarations wherever possible. 206 198 … … 219 211 ); 220 212 }}} 221 213 222 214 * Use STL when appropriate. 223 215 … … 225 217 226 218 * Avoid global state: global variables, static variables inside functions or inside classes, and singletons. 227 * When a module needs access to objects from outside its own environment, prefer to pass them in explicitly as arguments when instantiating that module, rather than making the objects global and having the module reach out to grab them.228 * When unavoidable, global variables should be named with a `g_` prefix.229 * Prefer global variables over singletons, because then they're not trying to hide their ugliness.219 * When a module needs access to objects from outside its own environment, prefer to pass them in explicitly as arguments when instantiating that module, rather than making the objects global and having the module reach out to grab them. 220 * When unavoidable, global variables should be named with a `g_` prefix. 221 * Prefer global variables over singletons, because then they're not trying to hide their ugliness. 230 222 231 223 * Don't do "`if (p) delete p;`". (That's redundant since "`delete NULL;`" is safe and does nothing.) … … 233 225 * If deleting a pointer, and it's not in a destructor, and it's not being immediately assigned a new value, use "`SAFE_DELETE(p)`" (which is equivalent to "`delete p; p = NULL;`") to avoid dangling pointers to deleted memory. 234 226 235 * Optimisations as you go from http://www.tantalon.com/pete/cppopt/main.htm (furthermost the "Pass Class Parameters by Reference" part.)227 * be sure to be aware of [CodeAndMemoryPerformance Code And Memory Performance] guidelines 236 228 237 229 == !JavaScript == 238 239 230 * Use the same basic formatting as described above for C++. 240 231 … … 282 273 283 274 == XML == 284 285 275 * All XML files should start with 286 276 {{{ 287 277 <?xml version="1.0" encoding="utf-8"?> 288 278 }}} 289 and be UTF-8 encoded (preferably without a BOM but that doesn't really matter).279 and be UTF-8 encoded (preferably without a BOM but that doesn't really matter). 290 280 291 281 * Empty-element tags should be written without a trailing space: use `<foo/>` or `<foo bar="baz"/>`, not `<foo />` nor `<foo bar="baz" />`.
