Gene Wirchenko said:
*
*
* This is a high-level comment.
*
*
This would be a comment in a language, where asterisk
alone can start a comment.
code && and this is a line comment.
This would be a comment in a language, where ampersands
start a comment.
Thank you, I later also became aware of this.
I dislike block ends at the end of a line.
One Way to Format Parentheses
There are several different ways to format texts with braces
and parentheses. One of them is being described here.
Indentation within Braces
An indentation of just one space often is too small to be seen
clearly, because the natural width and form of characters
often varies by an amount that is not very much smaller than a
space. Therefore, the indentation should amount to at least
two positions. In order not to waste horizontal spaces, an
indentation of exactly two positions is chosen. This means,
that the left position of the next level is two larger than
the position of the directly enclosing level.
Indentation by two positions within a block
{ ++x;
++x; }
^ ^
0 2
Bad: A small indentation by one position is not always visible
clearly
{++x;
++x; }
Good: The indentation by two positions is visible clearly
{ ++x;
++x; }
Bad: A large indentation by more than two positions wastes
horizontal space with no additional benefit
{ ++x;
++x; }
Spaces within braces
In mathematics, there are often no spaces at the inner side of
parentheses or braces in expressions, but spaces are used
indeed at the inner side of braces in set notation, when the
braces contain a description (not when they contain a list).
Spaces in set notation
{ x | x > 2 }
This style is adopted here: One space is written at the inner
side of braces.
Spaces at the inner side of parentheses within a block
{ ++x; }
This style is consistent with the indentation by two
positions, because only using this style, corresponding parts
of two lines have the same position.
Bad: No space after the first brace, the two statements are
misaligned
{++x;
++x; }
Good: One space after the first brace, the two statements are
properly aligned
{ ++x;
++x; }
Bad: Two spaces after the first brace, the two statements are
misaligned
{ ++x;
++x; }
There are some exceptions to this rule: No spaces are used
within empty braces "{}" and between two or more closing
braces of the same direction "}}", except, when the first one
of them is part of an empty pair "{} }" (an empty pair of
braces if treated like a single non-braces character).
Unified rules for all Brackets
For simplicity and uniformity, the rules from above apply to
all kinds of brackets, including parentheses, braces (curly
brackets), square brackets, and angle brackets.
Spaces within parentheses and square brackets
{ y = f( x )+ g() + a[ 2 ]; }
Binary operators are sorrounded by a space, but the space is
omitted, when there already is a space on the other side of a
sequence of brackets directly beside the operator: By this rule,
" )+" is written instead of " ) +".
Representation of the Syntactical Structure
A method or function definition consists of a head and a body.
The following representation shows this structure:
Good formatting according to the structure
void alpha() // head
{ beta(); } // body
The following formatting is misleading, because the line break
does not match the structural break:
Bad line break within the body
void alpha() { // head and the beginning of the body
beta(); } // the rest of the body
This formatting also would make no sense for blocks within
blocks. So it is often not used for such blocks. Therefore
even the adopters of this style can not use it uniformly.
Opening Braces Look Like "bullets"
There is a well known style to publish lists in typography
using bullets sticking out on the left, looking like this:
Common list representation with bullets in typography
o This is the first point
of this list, it is written
here just as an example.
o Here is another entry
o This is another example given
just as an example to show
an example
The braces of the beginnings of blocks stand out on the left
just the same, when the formatting being described here is
used, so they look quite naturally as beginning-of-a-block
markers, when one is used to the typographical list notation:
Left braces look like bullets to mark blocks
{ printf(); printf();
printf(); printf(); printf();
printf(); printf(); }
{ printf(); printf(); }
{ printf(); printf(); printf();
printf(); printf();
printf(); }
Neutrality
Someone wrote this C code:
while( fgets( eingabe, sizeof eingabe, stdin ))
if( sscanf( eingabe, "%d", &wert )!= 1 )
fprintf( stderr, "Please enter a number!\n" );
else
summe += wert;
It amazes me that I can add braces by my style conventions
(not changing the meaning of the code)
without the need to change the position of any character of
the given code or need to change the overall number of lines:
The code from above plus braces
while( fgets( eingabe, sizeof eingabe, stdin ))
{ if( sscanf( eingabe, "%d", &wert )!= 1 )
{ fprintf( stderr, "Please enter a number!\n" ); }
else
{ summe += wert; }}
Insofar, my bracing style might be considered non-obtrusive.
Lines per Contents
Lines containing only a single brace waste vertical space, so
less contents fits on the same screen space. Therefore, I usually
avoid them, but sometimes I do use them, when this helps to
increase readability. I also might temporarily use them when editing
a section of code. Of course, they would help programmers paid or
being judged by the lines-of-code productivity.
