Changes between Version 7 and Version 8 of Coding_Conventions

Timestamp:

Nov 24, 2011, 2:19:29 PM (12 years ago)

Author:

Philip Taylor

Comment:

more conventions

Coding_Conventions

@@ -96 +96 @@
  * 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.)
 
+ * Write switch statements like
+{{{
+switch (n)
+{
+case 10:
+    return 1;
+
+case 20:
+    foo();
+    // fall through to next case    [this should be explicit if you don't end with break or return]
+
+case 30:
+    bar();
+    break;
+
+case 40:
+{
+    int i = n*2;       // [need the extra {...} scope when declaring variables inside the case]
+    return i;
+}
+
+default:
+    debug_warn(L"invalid value for n");   // [only do this kind of warning if this case is an engine bug]
+}
+
+}}}
+
+=== Error reporting ===
+
+ * 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.)
+
+ * For error cases that could be triggered by modders (e.g. invalid data files), use
+{{{
+LOGERROR(L"Failed to load item %d from file %ls", i, path.c_str());
+}}}
+ This gets display on screen in red, and saved in the log files.
+ ''Exception:'' Code in `source/lib/` can't use `LOGERROR` (it can only use things defined in `source/lib/`).
+
+ * The engine should try to cope gracefully with `LOGERROR` cases, e.g. abort loading the current file; it should never crash in those cases.
+
 === Documentation ===
 
@@ -125 +165 @@
 === Strings ===
 
- * 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 conveniene.)
+ * 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.)
+  * ''Exception:'' `source/lib/` and `source/simulation2/` and `source/scriptinterface/` tend to prefer `std::[w]string` instead.
 
  * For portability, use the following formats for printf-style functions:
@@ -139 +180 @@
  * In header files, avoid `#include` and use forward declarations wherever possible.
 
+ * Sometimes it's nice to put `#include`s in alphabetical order.
+
  * Class names are !CamelCase and prefixed with `C`, e.g. `CGameObject`. Member functions are !CamelCase, e.g. `CGameObject::SetModifiedFlag(...)`. Member variables are !CamelCase prefixed with `m_`, e.g. `CGameObject::m_ModifiedFlag`. Files are named `GameObject.cpp`, `GameObject.h`, usually with one major class per file (possibly with some other support classes in the same files).
 
@@ -149 +192 @@
   * When unavoidable, global variables should be named with a `g_` prefix.
   * Prefer global variables over singletons, because then they're not trying to hide their ugliness.
+
+ * Don't do "`if (p) delete p;`". (That's redundant since "`delete NULL;`" is safe and does nothing.)
+
+ * 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.
+
+== !JavaScript ==
+
+ * Use the same basic formatting as described above for C++.
+
+ * Use roughly the same Doxygen-style comments for documentation as described above for C++. (But we don't actually run Doxygen on the JS code, so there's no need to make the comments use technically correct Doxygen syntax.)
+
+ * Don't omit the optional semicolons after statements.
+
+ * Use quotes around the key names in object literals:
+{{{
+var x = 100, y = 200;
+var pos = { "x": x, "y": y };
+}}}
+
+ * Create empty arrays and objects with "`[]`" and "`{}`" respectively, not with "`new Array()`" and "`new Object()`".
+
+ * Non-standard !SpiderMonkey extensions to the JS language may be used (though prefer to use equivalent standard features when possible). Documentation: [https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.6 1.6], [https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.7 1.7], [https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.8 1.8], [https://developer.mozilla.org/En/JavaScript/New_in_JavaScript/1.8.1 1.8.1], [https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.8.5 1.8.5], [https://developer.mozilla.org/en/JavaScript_typed_arrays typed arrays].
+
+ * To convert a string to a number, use the "`+`" prefix operator (not e.g. `parseInt`/`parseFloat`):
+{{{
+var a = "1";
+var b = a + 1;     // string concatenation; b == "11"
+var c = (+a) + 1;  // numeric addition; c == 2
+}}}