From 64323c3827a948523e28612a2281b4f43da0aaa4 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 6 Nov 2020 09:21:31 +0100 Subject: eng: Move code formatting rules into one section 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 (limited to 'eng') 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 `_.. -* 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..0053568 --- /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 appear on a line by itself at +the end. 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 -- cgit v1.2.3