[PATCH] eng: Move code formatting rules into one section

Sebastian Huber sebastian.huber at embedded-brains.de
Fri Nov 6 08:24:23 UTC 2020


Clarify the 80 character limit.  Change the line continuation indent
level.
---
 eng/coding-80cols.rst      | 154 -----------------------------
 eng/coding-conventions.rst |  26 -----
 eng/coding-formatting.rst  | 196 +++++++++++++++++++++++++++++++++++++
 eng/coding.rst             |   2 +-
 4 files changed, 197 insertions(+), 181 deletions(-)
 delete mode 100644 eng/coding-80cols.rst
 create mode 100644 eng/coding-formatting.rst

diff --git a/eng/coding-80cols.rst b/eng/coding-80cols.rst
deleted file mode 100644
index 85b838a..0000000
--- a/eng/coding-80cols.rst
+++ /dev/null
@@ -1,154 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2018.
-.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
-
-Eighty Character Line Limit
-***************************
-
-.. COMMENT: TBD - Convert the following to Rest and insert into this file
-.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line
-
- Code should look good for everyone under some standard width assumptions.
- Where a line wraps should be the same for anyone reading the code. For
- historical reasons, RTEMS uses 80 characters as the maximum width for each
- line of code.
-
-If you find yourself with code longer than 80 characters, first ask yourself
-whether the nesting level is too deep, names too long, compound expressions too
-complicated, or if some other guideline for improving readability can help to
-shrink the line length. Refactoring nested blocks into functions can help to
-alleviate code width problems while improving code readability. Making names
-descriptive yet terse can also improve readability. If absolutely necessary
-to have a long line, follow the rules on this page to break the line up to adhere
-to the 80 characters per line rule.
-
-Breaking long lines
--------------------
-
-``if``, ``while``, and ``for`` loops have their condition expressions aligned
-and broken on separate lines. When the conditions have to be broken, none go on
-the first line with the ``if``, ``while``, or ``for`` statement, and none go on
-the last line with the closing parenthesis and (optional) curly brace. Long
-statements are broken up and indented at operators, with an operator always
-being the last token on a line. No blank spaces should be left at the end of
-any line. Here is an example with a ``for`` loop.
-
-.. code-block:: c
-
-  for ( initialization = statement; a + really + long + statement + that + evaluates + to < a + boolean; another + statement++ ) {
-    z = a + really + long + statement + that + needs + two + lines + gets + indented + four + more + spaces + on + the + second + and + subsequent + lines + and + broken + up + at + operators;
-  }
-
-Should be replaced with
-
-.. code-block:: c
-
-  for (
-    initialization = statement;
-    a + really + long + statement + that + evaluates + to <
-    a + boolean;
-    another + statement++
-  ) {
-    z = a + really + long + statement + that + needs +
-        two + lines + gets + indented + four + more +
-        spaces + on + the + second + and + subsequent +
-        lines + and + broken + up + at + operators;
-  }
-
-Note that indentations should add 2 nesting levels (4 space characters, not tabs).
-
-Similarly,
-
-.. code-block:: c
-
-  if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) {
-
-should be broken up like
-
-.. code-block:: c
-
-  if (
-    this + that < those &&
-    this + these < that &&
-    this + those < these &&
-    this < those &&
-    those < that
-  ) {
-
-Note that each expression that resolves to a boolean goes on its own line.
-Where you place the boolean operator is a matter of choice.
-
-When a line is long because of a comment at the end, move the comment to
-just before the line, for example
-
-.. code-block:: c
-
-  #define A_LONG_MACRO_NAME (AND + EXPANSION) /* Plus + a + really + long + comment */
-
-can be replaced with
-
-.. code-block:: c
-
-  /* Plus + a + really + long + comment */
-  #define A_LONG_MACRO_NAME (AND + EXPANSION)
-
-C Preprocessor macros need to be broken up with some care, because the
-preprocessor does not understand that it should eat newline characters. So
-
-.. code-block:: c
-
-  #define A_LONG_MACRO_NAME (AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + DEFINED)
-
-would become
-
-.. code-block:: c
-
-  #define A_LONG_MACRO_NAME ( \
-    AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + \
-    DEFINED \
-  )
-
-Notice that each line is terminated by a backslash then the carriage return.
-The backslash tells the preprocessor to eat the newline. Of course, if you have
-such a long macro, you should consider not using a macro.
-
-Function declarations can be broken up at each argument, for example
-
-.. code-block:: c
-
-  int this_is_a_function( int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9 );
-
-would be broken up as
-
-.. code-block:: c
-
-  int this_is_a_function(
-    int arg1,
-    int arg2,
-    int arg3,
-    int arg4,
-    int arg5,
-    int arg6,
-    int arg7,
-    int arg8,
-    int arg9
-  );
-
-Excessively long comments should be broken up at a word boundary or somewhere
-that makes sense, for example
-
-.. code-block:: c
-
-  /* Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example */
-
-would be
-
-.. code-block:: c
-
-  /* Excessively long comments should be broken up at a word boundary or
-   * somewhere that makes sense, for example */
-
-Note that multiline comments have a single asterisk aligned with the asterisk
-in the opening ``/*``. The closing ``*/`` should go at the end of the last
-line.
diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst
index e34cd74..668a917 100644
--- a/eng/coding-conventions.rst
+++ b/eng/coding-conventions.rst
@@ -131,32 +131,6 @@ Language and Compiler
 
 * Do not use the register keyword. It is deprecated since C++14.
 
-Formatting
------------
-
-* Use spaces instead of tabs.
-* Use two spaces for indentation, four spaces for
-  hanging indentation.
-* Adhere to a limit of `80 characters per line <https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line>`_..
-* Put function return types and names on one line if they fit.
-* Put function calls on one line if they fit.
-* No space between a function name or function-like macro and
-  the opening parens.
-* Put braces on the same line as and one space after the
-  conditional expression ends.
-* Put the opening brace of a function definition one line after
-  the closing parenthesis of its prototype.
-* Put a single space inside and outside of each parenthesis
-  of a conditional expression.
-  * Exception: never put a space before a closing semi-colon.
-* Put a single space before and after ternary operators.
-* Put a single space before and after binary operators.
-* Put no space between unary operators (e.g. *, &, !, ~, ++, --)
-  and their operands.
-* No spaces around dereferencing operators (-> and .).
-* Do not use more than one blank line in a row.
-* Do not use trailing whitespace at the end of a line.
-
 Readability
 ------------
 
diff --git a/eng/coding-formatting.rst b/eng/coding-formatting.rst
new file mode 100644
index 0000000..f606a60
--- /dev/null
+++ b/eng/coding-formatting.rst
@@ -0,0 +1,196 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+Formatting
+**********
+
+Rules
+-----
+
+* Adhere to the :ref:`EightyCharacterLineLimit`.
+
+* Use spaces instead of tabs.
+
+* Use two spaces for one indentation level.
+
+* Put function return types and names on one line if they fit.
+
+* Put function calls on one line if they fit.
+
+* No space between a function name or function-like macro and
+  the opening parenthesis.
+
+* Put braces on the same line as and one space after the
+  conditional expression ends.
+
+* Put the opening brace of a function definition one line after the closing
+  parenthesis of its prototype.
+
+* Put a single space inside and outside of each parenthesis of a conditional
+  expression.  Exception: never put a space before a closing semi-colon.
+
+* Put a single space before and after ternary operators.
+
+* Put a single space before and after binary operators.
+
+* Put no space between unary operators (e.g. ``*``, ``&``, ``!``, ``~``, ``++``, ``--``)
+  and their operands.
+
+* No spaces around dereferencing operators (``->`` and ``.``).
+
+* Do not use more than one blank line in a row.
+
+* Do not use trailing white space at the end of a line.
+
+.. _EightyCharacterLineLimit:
+
+Eighty Character Line Limit
+---------------------------
+
+Code should look good for everyone under some standard width assumptions.
+Where a line wraps should be the same for anyone reading the code.  For
+historical reasons, RTEMS uses 80 characters as the maximum width for each line
+of code.  The newline (``\n``) character terminating the line does not count
+for the 80 character limit.
+
+If you find yourself with code longer than 80 characters, first ask yourself
+whether the nesting level is too deep, names too long, compound expressions too
+complicated, or if some other guideline for improving readability can help to
+shrink the line length.  Refactoring nested blocks into functions can help to
+alleviate code width problems while improving code readability.  Making names
+descriptive yet terse can also improve readability.  If absolutely necessary to
+have a long line, follow the rules on this page to break the line up to adhere
+to the 80 characters per line rule.
+
+Breaking Long Lines
+-------------------
+
+The ``if``, ``while``, and ``for`` control statements have their condition
+expressions aligned and broken on separate lines.  When the conditions have to
+be broken, none go on the first line with the ``if``, ``while``, or ``for``
+statement, and none go on the last line with the closing parenthesis and the
+curly brace.  Long statements are broken up and indented at operators, with an
+operator always being the last token on a line.  No blank spaces should be left
+at the end of any line.  The continuation of a broken line is indented by one
+level.  Here is an example with a ``for`` loop.
+
+.. code-block:: c
+
+  for ( initialization = statement; a + really + longish + statement + that + evaluates + to < a + boolean; another + statement ) {
+    some_variable = a + really + longish + statement + that + needs + two + lines + gets + indented + four + more + spaces + on + the + second + and + subsequent + lines + and + broken + up + at + operators;
+  }
+
+Should be replaced with
+
+.. code-block:: c
+
+  for (
+    initialization = statement;
+    a + really + longish + statement + that + evaluates + to <
+      a + boolean;
+    another + statement
+  ) {
+    some_variable = a + really + longish + statement + that + needs +
+      two + lines + gets + indented + four + more +
+      spaces + on + the + second + and + subsequent +
+      lines + and + broken + up + at + operators;
+  }
+
+Similarly,
+
+.. code-block:: c
+
+  if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) {
+
+should be broken up like
+
+.. code-block:: c
+
+  if (
+    this + that < those &&
+    this + these < that &&
+    this + those < these &&
+    this < those &&
+    those < that
+  ) {
+
+Note that each expression that resolves to a boolean goes on its own line.
+Where you place the boolean operator is a matter of choice.
+
+When a line is long because of a comment at the end, move the comment to
+just before the line, for example
+
+.. code-block:: c
+
+  #define A_LONG_MACRO_NAME (AND + EXPANSION) /* Plus + a + really + long + comment */
+
+can be replaced with
+
+.. code-block:: c
+
+  /* Plus + a + really + long + comment */
+  #define A_LONG_MACRO_NAME (AND + EXPANSION)
+
+C Preprocessor macros need to be broken up with some care, because the
+preprocessor does not understand that it should eat newline characters. So
+
+.. code-block:: c
+
+  #define A_LONG_MACRO_NAME (AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + DEFINED)
+
+would become
+
+.. code-block:: c
+
+  #define A_LONG_MACRO_NAME ( \
+    AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + \
+    DEFINED \
+  )
+
+Notice that each line is terminated by a backslash.
+The backslash tells the preprocessor to eat the newline. Of course, if you have
+such a long macro, you should consider not using a macro.
+
+Function declarations can be broken up at each argument, for example
+
+.. code-block:: c
+
+  int this_is_a_function( int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9 );
+
+would be broken up as
+
+.. code-block:: c
+
+  int this_is_a_function(
+    int arg1,
+    int arg2,
+    int arg3,
+    int arg4,
+    int arg5,
+    int arg6,
+    int arg7,
+    int arg8,
+    int arg9
+  );
+
+Excessively long comments should be broken up at a word boundary or somewhere
+that makes sense, for example
+
+.. code-block:: c
+
+  /* Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example */
+
+would be
+
+.. code-block:: c
+
+  /*
+   * Excessively long comments should be broken up at a word boundary or
+   * somewhere that makes sense, for example.
+   */
+
+Note that multiline comments have a single asterisk aligned with the asterisk
+in the opening ``/*``. The closing ``*/`` should go at the end of the last
+line.
diff --git a/eng/coding.rst b/eng/coding.rst
index 6cba22a..692f9aa 100644
--- a/eng/coding.rst
+++ b/eng/coding.rst
@@ -12,7 +12,7 @@ TBD  - Write introduction, re-order, identify missing content
 .. toctree::
 
     coding-conventions
-    coding-80cols
+    coding-formatting
     coding-deprecating
     coding-doxygen
     coding-file-hdr
-- 
2.26.2



More information about the devel mailing list