syncing with src/CodingStyle

Author: hansu

docs/src/code/style-guide.adoc

@@ -38,6 +38,24 @@ Do not use an editor that makes unneeded changes to whitespace (e.g.,
 which replaces 8 spaces with a tabstop on a line not otherwise
 modified, or word-wraps lines not otherwise modified).
 
+=== Translations
+
+All program code and documentation is written in US English.
+All translations (which soon includes the documentation) are performed
+with the help of the (https://hosted.weblate.org/projects/linuxcnc/)[weblate]
+services. Our users and developers are kindly asked to help with the
+translation. The source tree then maintains the .po files in sync with that online
+representation.
+
+
+
+== C/C++ coding standards
+
+Most of this style guide has been copied wholesale from the Linux kernel
+documents - See linux/Documentation/CodingStyle for the full text.
+The C++ recommendations have been drawn from various sources such as the
+GTK headers, "C++ The Complete Reference" by Schildt, and IRC discussions.
+
 === Tab Stops
 
 A tab stop always corresponds to 8 spaces. Do not write code that
@@ -48,55 +66,68 @@ displays correctly only with a differing tab stop setting.
 Use 4 spaces per level of indentation. Combining 8 spaces into one tab
 is acceptable but not required.
 
-=== Translations
+Rationale: The whole idea behind indentation is to clearly define where
+a block of control starts and ends.  Especially when you've been looking
+at your screen for 20 straight hours, you'll find it a lot easier to see
+how the indentation works if you have large indentations.
 
-All program code and documentation is written in US English.
-All translations (which soon includes the documentation) are performed
-with the help of the (https://hosted.weblate.org/projects/linuxcnc/)[weblate]
-services. Our users and developers are kindly asked to help with the
-translation. The source tree then maintains the .po files in sync with that online
-representation.
-
-== Code implementing functionality for the machine
+Now, some people will claim that having 8-character indentations makes
+the code move too far to the right, and makes it hard to read on a
+80-character terminal screen. Whilst the GNU style of 2-character
+indentations reduces the clarity. For EMC2, a compromise of 4-character
+indentation has been chosen. This still spreads the code out and causes
+lines to wrap round leading to difficulties in reading the sources. The
+answer to that is that if you need more than 3 levels of indentation, you're
+screwed anyway, and should fix your program.
 
 === Placing Braces
 
-Put the opening brace last on the line, and put the closing brace first:
-
+The other issue that always comes up in C styling is the placement of
+braces.  Unlike the indent size, there are few technical reasons to
+choose one placement strategy over the other, but the preferred way, as
+shown to us by the prophets Kernighan and Ritchie, is to put the opening
+brace last on the line, and put the closing brace first, thusly:
 [source,c]
 ----
-if (x) {
-    // do something appropriate
+if (x is true) {
+    we do y
 }
 ----
-
-The closing brace is on a line of its own, except in the cases where
-it is followed by a continuation of the same statement, i.e. a 'while'
-in a do-statement or an 'else' in an if-statement, like this:
-
+However, there is one special case, namely functions: they have the
+opening brace at the beginning of the next line, thus:
+[source,c]
+----
+int function(int x)
+{
+    body of function
+}
+----
+Note that the closing brace is empty on a line of its own, _except_ in
+the cases where it is followed by a continuation of the same statement,
+i.e. a "while" in a do-statement or an "else" in an if-statement, like
+this:
 [source,c]
 ----
 do {
-    // something important
-} while (x > 0);
+    body of do-loop
+} while (condition);
 ----
-
 and
-
 [source,c]
 ----
 if (x == y) {
-    // do one thing
-} else if (x < y) {
-    // do another thing
+    ..
+} else if (x > y) {
+    ...
 } else {
-    // do a third thing
+    ....
 }
 ----
-
-This brace-placement also minimizes the number of empty (or almost
-empty) lines, which allows a greater amount of code or comments to be
-visible at once in a terminal of a fixed size.
+Also, note that this brace-placement also minimizes the number of empty
+(or almost empty) lines, without any loss of readability.  Thus, as the
+supply of new-lines on your screen is not a renewable resource (think
+25-line terminal screens here), you have more empty lines to put
+comments on.
 
 === Naming
 
@@ -226,7 +257,7 @@ be avoided as much as possible. Rationale: Clarifies which are
 variables and which are methods. Public: e.g., axislimit Private: e.g.,
 maxvelocity_ .
 
-=== Specific method naming conventions
+.Specific method naming conventions
 
 The terms get and set should be used where an attribute is accessed
 directly. Rationale: Indicates the purpose of the function or method,
@@ -266,15 +297,51 @@ Implicit tests for zero should not be used except for boolean
 variables, e.g., `if (spindle_speed != 0)` NOT `if (spindle_speed)`.
 
 Only loop control statements must be included in a for() construct,
-e.g., `sum = 0; for (i=0; i<10; i++) { sum += value[i]; }` +
-NOT: `for (i=0, sum=0; i<10; i++) sum += value[i];`.
+e.g.
+[source,c]
+----
+sum = 0;
+for (i = 0; i < 10; i++) {
+    sum += value[i];
+}
+----
+NOT:
+[source,c]
+----
+for (i = 0, sum = 0; i < 10; i++) {
+    sum += value[i];
+}
+----
 
 Likewise, executable statements in conditionals must be avoided, e.g.,
-`if (fd = open(file_name)` is bad.
+`if (fd = open(file_name))` is bad.
 
 Complex conditional statements should be avoided - Introduce temporary
 boolean variables instead.
 
+The form `while(true)`` should be used for infinite loops.
+ e.g.
+[source,c]
+----
+while (true) {
+    ...;
+}
+----
+NOT
+[source,c]
+----
+for (;;) {
+    ...;
+}
+----
+or
+[source,c]
+----
+while (1) {
+    ...;
+}
+----
+
 Parentheses should be used in plenty in mathematical expressions - Do
 not rely on operator precedence when an extra parentheses would clarify
 things.