Changeset 8059b68 in rtems-docs


Ignore:
Timestamp:
Dec 1, 2018, 5:11:15 PM (5 months ago)
Author:
Marçal Comajoan Cara <mcomajoancara@…>
Branches:
master
Children:
65476b4
Parents:
49453ec
git-author:
Marçal Comajoan Cara <mcomajoancara@…> (12/01/18 17:11:15)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:34:58)
Message:

eng/coding-80cols: Convert wiki page to Rest

Converted https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line
to Rest, and TBDs into comments.

This work was part of GCI 2018.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • eng/coding-80cols.rst

    r49453ec r8059b68  
    77***************************
    88
    9 TBD  - Convert the following to Rest and insert into this file
    10 TBD - https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line
     9.. COMMENT: TBD - Convert the following to Rest and insert into this file
     10.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line
     11
     12 Code should look good for everyone under some standard width assumptions.
     13 Where a line wraps should be the same for anyone reading the code. For
     14 historical reasons, RTEMS uses 80 characters as the maximum width for each
     15 line of code.
     16
     17If you find yourself with code longer than 80 characters, first ask yourself
     18whether the nesting level is too deep, names too long, compound expressions too
     19complicated, or if some other guideline for improving readability can help to
     20shrink the line length. Refactoring nested blocks into functions can help to
     21alleviate code width problems while improving code readability. Making names
     22descriptive yet terse can also improve readability. If absolutely necessary
     23to have a long line, follow the rules on this page to break the line up to adhere
     24to the 80 characters per line rule.
     25
     26Breaking long lines
     27-------------------
     28
     29``if``, ``while``, and ``for`` loops have their condition expressions aligned
     30and broken on separate lines. When the conditions have to be broken, none go on
     31the first line with the ``if``, ``while``, or ``for`` statement, and none go on
     32the last line with the closing parenthesis and (optional) curly brace. Long
     33statements are broken up and indented at operators, with an operator always
     34being the last token on a line. No blank spaces should be left at the end of
     35any line. Here is an example with a ``for`` loop.
     36
     37.. code-block:: c
     38
     39  for ( initialization = statement; a + really + long + statement + that + evaluates + to < a + boolean; another + statement++ ) {
     40    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;
     41  }
     42
     43Should be replaced with
     44
     45.. code-block:: c
     46
     47  for (
     48    initialization = statement;
     49    a + really + long + statement + that + evaluates + to <
     50    a + boolean;
     51    another + statement++
     52  ) {
     53    z = a + really + long + statement + that + needs +
     54        two + lines + gets + indented + four + more +
     55        spaces + on + the + second + and + subsequent +
     56        lines + and + broken + up + at + operators;
     57  }
     58
     59Note that indentations should add 2 nesting levels (4 space characters, not tabs).
     60
     61Similarly,
     62
     63.. code-block:: c
     64
     65  if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) {
     66
     67should be broken up like
     68
     69.. code-block:: c
     70
     71  if (
     72    this + that < those &&
     73    this + these < that &&
     74    this + those < these &&
     75    this < those &&
     76    those < that
     77  ) {
     78
     79Note that each expression that resolves to a boolean goes on its own line.
     80Where you place the boolean operator is a matter of choice.
     81
     82When a line is long because of a comment at the end, move the comment to
     83just before the line, for example
     84
     85.. code-block:: c
     86
     87  #define A_LONG_MACRO_NAME (AND + EXPANSION) /* Plus + a + really + long + comment */
     88
     89can be replaced with
     90
     91.. code-block:: c
     92
     93  /* Plus + a + really + long + comment */
     94  #define A_LONG_MACRO_NAME (AND + EXPANSION)
     95
     96C Preprocessor macros need to be broken up with some care, because the
     97preprocessor does not understand that it should eat newline characters. So
     98
     99.. code-block:: c
     100
     101  #define A_LONG_MACRO_NAME (AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + DEFINED)
     102
     103would become
     104
     105.. code-block:: c
     106
     107  #define A_LONG_MACRO_NAME ( \
     108    AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + \
     109    DEFINED \
     110  )
     111
     112Notice that each line is terminated by a backslash then the carriage return.
     113The backslash tells the preprocessor to eat the newline. Of course, if you have
     114such a long macro, you should consider not using a macro.
     115
     116Function declarations can be broken up at each argument, for example
     117
     118.. code-block:: c
     119
     120  int this_is_a_function( int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9 );
     121
     122would be broken up as
     123
     124.. code-block:: c
     125
     126  int this_is_a_function(
     127    int arg1,
     128    int arg2,
     129    int arg3,
     130    int arg4,
     131    int arg5,
     132    int arg6,
     133    int arg7,
     134    int arg8,
     135    int arg9
     136  );
     137
     138Excessively long comments should be broken up at a word boundary or somewhere
     139that makes sense, for example
     140
     141.. code-block:: c
     142
     143  /* Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example */
     144
     145would be
     146
     147.. code-block:: c
     148
     149  /* Excessively long comments should be broken up at a word boundary or
     150   * somewhere that makes sense, for example */
     151
     152Note that multiline comments have a single asterisk aligned with the asterisk
     153in the opening ``/*``. The closing ``*/`` should go at the end of the last
     154line.
Note: See TracChangeset for help on using the changeset viewer.