1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2018. |
---|
4 | .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project |
---|
5 | |
---|
6 | Eighty Character Line Limit |
---|
7 | *************************** |
---|
8 | |
---|
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 | |
---|
17 | If you find yourself with code longer than 80 characters, first ask yourself |
---|
18 | whether the nesting level is too deep, names too long, compound expressions too |
---|
19 | complicated, or if some other guideline for improving readability can help to |
---|
20 | shrink the line length. Refactoring nested blocks into functions can help to |
---|
21 | alleviate code width problems while improving code readability. Making names |
---|
22 | descriptive yet terse can also improve readability. If absolutely necessary |
---|
23 | to have a long line, follow the rules on this page to break the line up to adhere |
---|
24 | to the 80 characters per line rule. |
---|
25 | |
---|
26 | Breaking long lines |
---|
27 | ------------------- |
---|
28 | |
---|
29 | ``if``, ``while``, and ``for`` loops have their condition expressions aligned |
---|
30 | and broken on separate lines. When the conditions have to be broken, none go on |
---|
31 | the first line with the ``if``, ``while``, or ``for`` statement, and none go on |
---|
32 | the last line with the closing parenthesis and (optional) curly brace. Long |
---|
33 | statements are broken up and indented at operators, with an operator always |
---|
34 | being the last token on a line. No blank spaces should be left at the end of |
---|
35 | any 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 | |
---|
43 | Should 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 | |
---|
59 | Note that indentations should add 2 nesting levels (4 space characters, not tabs). |
---|
60 | |
---|
61 | Similarly, |
---|
62 | |
---|
63 | .. code-block:: c |
---|
64 | |
---|
65 | if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) { |
---|
66 | |
---|
67 | should 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 | |
---|
79 | Note that each expression that resolves to a boolean goes on its own line. |
---|
80 | Where you place the boolean operator is a matter of choice. |
---|
81 | |
---|
82 | When a line is long because of a comment at the end, move the comment to |
---|
83 | just 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 | |
---|
89 | can be replaced with |
---|
90 | |
---|
91 | .. code-block:: c |
---|
92 | |
---|
93 | /* Plus + a + really + long + comment */ |
---|
94 | #define A_LONG_MACRO_NAME (AND + EXPANSION) |
---|
95 | |
---|
96 | C Preprocessor macros need to be broken up with some care, because the |
---|
97 | preprocessor 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 | |
---|
103 | would 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 | |
---|
112 | Notice that each line is terminated by a backslash then the carriage return. |
---|
113 | The backslash tells the preprocessor to eat the newline. Of course, if you have |
---|
114 | such a long macro, you should consider not using a macro. |
---|
115 | |
---|
116 | Function 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 | |
---|
122 | would 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 | |
---|
138 | Excessively long comments should be broken up at a word boundary or somewhere |
---|
139 | that 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 | |
---|
145 | would 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 | |
---|
152 | Note that multiline comments have a single asterisk aligned with the asterisk |
---|
153 | in the opening ``/*``. The closing ``*/`` should go at the end of the last |
---|
154 | line. |
---|