Changes between Version 30 and Version 31 of Coding_Conventions

Timestamp:

Jan 10, 2017, 1:34:41 AM (7 years ago)

Author:

s0600204

Comment:

Bump to 2017, and have a go at adding conventions adopted over the past year (or two).

Coding_Conventions

@@ -17 +17 @@
 {{{
 #!cpp
-/* Copyright (C) 2016 Wildfire Games.
+/* Copyright (C) 2017 Wildfire Games.
  * This file is part of 0 A.D.
  *
@@ -39 +39 @@
 {{{
 #!cpp
-/* Copyright (c) 2016 Wildfire Games
+/* Copyright (c) 2017 Wildfire Games
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -123 +123 @@
 }
 
+case 50:
+{
+    int z = n*2;
+    n = foobar(n, z);
+    break;             // [place breaks inside the brackets]
+}
+
 default:
     debug_warn(L"invalid value for n");   // [only do this kind of warning if this case is an engine bug]
@@ -236 +243 @@
 std::vector<T> anyVector;
 std::for_each(anyVector.begin(), anyVector.end(), [] (const T& element){
-   //code
+   // code
 }
 
@@ -242 +249 @@
 for (const T& element : anyVector)
 {
-   //code
+   // code
 }
 }}}
@@ -256 +263 @@
 {
    return param + optionalParam;
+}
+}}}
+
+ * In `c++11`, it is possible to use the `auto` type-specifier, wherein the appropriate data-type is determined at compile time. Although potentially useful, overuse can cause serious problems in the long-run. Therefore, this code feature should be used in moderation. Specifically:
+   - It should be clear from reading the code what type the `auto` is replacing. (Add a comment if necessary.)
+   - It should only ever be used as a replacement for an iterator type.
+   - It should only be used if the data-type-specifier it is standing in for is long. As a rule of thumb, if the line would be shorter than your chosen suitable line width (see convention on avoiding wide lines under [#Formatting formatting] above) without it, don't use it.
+
+ * Favour early returns where possible. The following:
+{{{
+#!cpp
+void foo(bool x)
+{
+    if (x)
+    {
+        /* lines */
+    }
+}
+}}}
+   is better when written like:
+{{{
+#!cpp
+void foo(bool x)
+{
+    if (!x)
+        return;
+
+    /* lines */
 }
 }}}
@@ -269 +304 @@
 {{{
 #!js
-var x = 100, y = 200;
-var pos = { "x": x, "y": y };
+let x = 100, y = 200;
+let pos = { "x": x, "y": y };
 }}}
 
  * Create empty arrays and objects with "`[]`" and "`{}`" respectively, not with "`new Array()`" and "`new Object()`".
 
+ * Global variables and constants are named with a `g_` prefix and the rest of the name in !CamelCase, ie. `var g_ParsedData` or `const g_BarterActions`.
+
  * 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].
 
@@ -280 +317 @@
 {{{
 #!js
-var a = "1";
-var b = a + 1;     // string concatenation; b == "11"
-var c = (+a) + 1;  // numeric addition; c == 2
+let a = "1";
+let b = a + 1;     // string concatenation; b == "11"
+let c = (+a) + 1;  // numeric addition; c == 2
 }}}
 
@@ -304 +341 @@
 }}}
 
+ * Use `var` only when declaring variables in the global scope. When inside functions, ifs, loops, etc., use `let`. We prefer `let` because:
+   - It is restricted to the scope it is declared in, preventing unintentional clobbering of values
+   - It is stricter than `var`, and throws an error if it a variable is declared twice within the same scope
+{{{
+#!js
+{
+  var x = 1;
+  var x = "foo" // No Error
+}
+
+{
+  let x = 1;
+  let x = "foo"; // TypeError: redeclaration of let x
+}
+}}}
+
 == XML ==
  * All XML files should start with