kopia lustrzana https://github.com/Hamlib/Hamlib
Modified coding style to Allman
Revised astylerc to use allman brace style and to keep one-line blocks and one-line statements.pull/1/head
rodzic
028732bdfd
commit
ef3620defb
|
@ -36,9 +36,11 @@ in rehashing that here, except to say that spaces are universal. Modern
|
||||||
editors are configurable to setting indents to four spaces and tab stops to
|
editors are configurable to setting indents to four spaces and tab stops to
|
||||||
four spaces.
|
four spaces.
|
||||||
|
|
||||||
* Bare conditionals shall not be permitted. All conditionals--'if', 'else',
|
* Bare conditionals shall be avoided. All conditionals--'if', 'else', 'for',
|
||||||
'for', 'while', and 'do while' shall have their statements enclosed in
|
'while', and 'do while' shall have their statements enclosed in braces.
|
||||||
braces.
|
|
||||||
|
NOTE: Exceptions will be allowed in certain rare circumstances. See
|
||||||
|
Recommended coding style bullet points below.
|
||||||
|
|
||||||
Discussion: Consider this conditional:
|
Discussion: Consider this conditional:
|
||||||
|
|
||||||
|
@ -46,19 +48,20 @@ Discussion: Consider this conditional:
|
||||||
do_that();
|
do_that();
|
||||||
|
|
||||||
No harm, eh? Look again. The programmer gave the 'if' conditional a null
|
No harm, eh? Look again. The programmer gave the 'if' conditional a null
|
||||||
statement with the trailing ';' at the end of the line. As a result,
|
statement with the trailing ';' at the end of the line and also indented the
|
||||||
'do_that()' will be called whether 'something' is true or not. Most likely
|
'do_that();' statement. As a result, 'do_that()' will be called whether
|
||||||
this is not what the programmer intended!
|
'something' is true or not. Is that what the programmer intended?
|
||||||
|
|
||||||
If, instead, the code is reformatted to:
|
If, instead, the code is formatted to:
|
||||||
|
|
||||||
if (something) {
|
if (something)
|
||||||
|
{
|
||||||
;
|
;
|
||||||
do_that();
|
do_that();
|
||||||
}
|
}
|
||||||
|
|
||||||
by a code formatter, the null statement becomes harmless and 'do_that()' is
|
the null statement becomes harmless and 'do_that()' is called depending on the
|
||||||
called depending on the truth of 'something'.
|
truth of 'something'.
|
||||||
|
|
||||||
Here proper indentation and alignment is only half the battle in finding such
|
Here proper indentation and alignment is only half the battle in finding such
|
||||||
bugs, enclosing all statement blocks in braces is the other half.
|
bugs, enclosing all statement blocks in braces is the other half.
|
||||||
|
@ -75,32 +78,33 @@ formatter will apply when using the included 'scripts/astylerc' configuration
|
||||||
file. Any version from 2.03 or later should work. It can be invoked from a
|
file. Any version from 2.03 or later should work. It can be invoked from a
|
||||||
backend directory as follows:
|
backend directory as follows:
|
||||||
|
|
||||||
$ astyle --options=../scripts/astylerc moonmelter.c
|
$ astyle --options=../scripts/astylerc moonmelter.c
|
||||||
|
|
||||||
The old file will be copied to 'moonmelter.c.orig' as a back up.
|
The old file will be copied to 'moonmelter.c.orig' as a back up.
|
||||||
|
|
||||||
* Brace style is K&R where the opening brace of a function definition is on a
|
* Brace style is Allman where the opening brace of a function definition is on
|
||||||
new line in the far left column following the function signature. For
|
a new line in the far left column following the function signature.
|
||||||
conditionals, the opening brace is at the end of the conditional one space
|
|
||||||
after the closing parentheses. In all cases the closing brace is on a line
|
For conditionals, the opening brace is also on a new line after the
|
||||||
of its own and lines up vertically with the conditional key word. The
|
conditional test and aligned in the same column as the first letter of the
|
||||||
exception (there is always at least one) is when 'else', 'else if, or
|
keyword.
|
||||||
'while' from a 'do while' loop are cuddled after the closing brace. See
|
|
||||||
'src/rig.c' for many examples.
|
In all cases the closing brace is on a line of its own and lines up
|
||||||
|
vertically with the opening brace.
|
||||||
|
|
||||||
|
The 'else', 'else if', or 'while' from a 'do while' loop keywords are not
|
||||||
|
cuddled after the closing brace but placed on a new line after the closing
|
||||||
|
brace of the previous block.
|
||||||
|
|
||||||
* Indents are four spaces as detailed above. Each level of code should be one
|
* Indents are four spaces as detailed above. Each level of code should be one
|
||||||
indent further to the right. An exception is where a conditional needs to
|
indent further to the right.
|
||||||
be split over multiple lines and an extra indentation provides more
|
|
||||||
readability of the statement block. See 'src/rig.c' for many examples.
|
|
||||||
|
|
||||||
* Isolate conditional blocks with a blank line before and after. Like
|
* Isolate conditional blocks with a blank line before and after. Like
|
||||||
paragraphs in prose that focus on a topic, it's important that conditionals
|
paragraphs in prose that focus on a topic, it's important that conditionals
|
||||||
be obvious to the reader. An exception is where another conditional follows
|
be obvious to the reader. An exception is where another conditional follows
|
||||||
immediately on the next line. Indentation is sufficient. See 'src/rig.c'
|
immediately on the next line. Indentation is sufficient.
|
||||||
for many examples.
|
|
||||||
|
|
||||||
* No space between parentheses and the enclosed characters. You know where to
|
* No space between parentheses and the enclosed characters.
|
||||||
look by now. ;-)
|
|
||||||
|
|
||||||
* One space on either side of operators and between function arguments.
|
* One space on either side of operators and between function arguments.
|
||||||
|
|
||||||
|
@ -116,18 +120,28 @@ The old file will be copied to 'moonmelter.c.orig' as a back up.
|
||||||
|
|
||||||
* Keep code lines under 80 characters. This will require some judgement on
|
* Keep code lines under 80 characters. This will require some judgement on
|
||||||
where the break works best. A couple of keys are, a) break conditionals
|
where the break works best. A couple of keys are, a) break conditionals
|
||||||
before a comparison operator so it appears at the front of the next line,
|
before a comparison operator so it appears at the beginning of the next
|
||||||
and, b) when breaking a function call, put all arguments on their own line.
|
line, and, b) when breaking a function call, put all arguments on their own
|
||||||
It is sometimes necessary for strings to go beyond the 80 character point.
|
line. It is sometimes necessary for strings to go beyond the 80 character
|
||||||
This is fine. If needed, a C compiler will concatenate strings that are
|
point. This is fine. If needed, a C compiler will concatenate strings that
|
||||||
split across multiple lines.
|
are split across multiple lines.
|
||||||
|
|
||||||
* Avoid trailing comments when possible. Comments should precede the
|
* Avoid trailing comments when possible. Comments should precede the
|
||||||
statement(s) they describe.
|
statement(s) they describe.
|
||||||
|
|
||||||
* When a conditional is split across mutliple lines, readability of the
|
* One line conditionals should enclose the statement in braces, as in:
|
||||||
following statement can be aided by a blank line above the statement and/or
|
|
||||||
an extra level of indentation.
|
if (whatsit == 5) { return whatsit; }
|
||||||
|
|
||||||
|
or:
|
||||||
|
|
||||||
|
do { x++; } while (x < 10)
|
||||||
|
|
||||||
|
When choosing not to use braces on a simple one line conditional, please
|
||||||
|
comment your intention:
|
||||||
|
|
||||||
|
/* NOP unless x is true. */
|
||||||
|
while (!x);
|
||||||
|
|
||||||
|
|
||||||
4. Use of code formatting tools
|
4. Use of code formatting tools
|
||||||
|
@ -141,7 +155,7 @@ Use of the Artistic Style (astyle) formatter (http://astyle.sourceforge.net/)
|
||||||
with the included options file ('scripts/astylerc') will provide most of the
|
with the included options file ('scripts/astylerc') will provide most of the
|
||||||
objectives outlined above. Some manual formatting may be required. For
|
objectives outlined above. Some manual formatting may be required. For
|
||||||
example, if a line is already less than 80 characters and ends with an
|
example, if a line is already less than 80 characters and ends with an
|
||||||
operator, astyle will not move the operator to the front of the next line
|
operator, astyle will not move the operator to the beginning of the next line
|
||||||
where it is preferred.
|
where it is preferred.
|
||||||
|
|
||||||
4.2 GNU Indent
|
4.2 GNU Indent
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
# astylerc--custom options for astyle
|
# astylerc--custom options for astyle
|
||||||
|
|
||||||
# K&R style formatting/indenting with some tweaks.
|
# K&R style formatting/indenting with some tweaks.
|
||||||
style=kr
|
style=allman
|
||||||
|
|
||||||
# Indent with a width of 4 spaces.
|
# Indent with a width of 4 spaces.
|
||||||
indent=spaces=4
|
indent=spaces=4
|
||||||
|
@ -27,6 +27,12 @@ align-reference=type
|
||||||
# (e.g. 'if', 'for', 'while'...).
|
# (e.g. 'if', 'for', 'while'...).
|
||||||
add-brackets
|
add-brackets
|
||||||
|
|
||||||
|
# Don't break one-line blocks.
|
||||||
|
keep-one-line-blocks
|
||||||
|
|
||||||
|
# Don't break complex statements and multiple statements residing on a single line.
|
||||||
|
keep-one-line-statements
|
||||||
|
|
||||||
# Converts tabs into spaces in the non-indentation part of the line.
|
# Converts tabs into spaces in the non-indentation part of the line.
|
||||||
convert-tabs
|
convert-tabs
|
||||||
|
|
||||||
|
|
Ładowanie…
Reference in New Issue