Indentation styles

markspace <markspace@nospam.nospam> writes:


  The formatting too is part of the message I want to convey,
  so to me it would not be the same message anymore.

  If someone is paying me to write code, he can get any format
  from me that he likes. But on the Usenet I enjoy the freedom
  to use the indentation style that I deem best, as explained below:

  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 is 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.

  The Formatting of The If Statement

  I want my code to express the structure of the if
  statement.

  What is the structure of an if statement?

  According to ISO/IEC 9899:1999 (E) [it is similar in the
  JLS {Java}, too]

selection-statement:
if ( expression )
statement

  So, there is a head clause

if ( expression )

  and a body statement

statement

  Thus,

if( expression ) /* head clause */
{ exam(); ple(); } /* body statement */

  The separation between head and body in the deep structure
  beautifully alignes with the separation between the first
  and the second line in the visible surface structure. Thus,
  the surface structure exposes the deep structure in a
  not-misleading way. (Which to me is the generalized meaning
  of ?structured programming?: expressing as much of the deep
  structure as possible already in the surface structure,
  which makes the code more readable.)

  Moreover, why would anyone sane in his mind compose a line
  of the head of a structure /and the first character of its
  body/ with the rest of the body following in another line?

if( expression ) { /* head clause AND first character
                        of the body statement */
  exam(); ple(); /* rest of body, except for */
} /* a line wasted on a brace */

  As a comparision, in writing, we have headings and text body:

      The Creation

      In the beginning God created the heaven and the earth.

  Now, why would someone write the heading /and the first word of
  its body/ on a line, as in the following example?

      The Creation In

      the beginning God created the heaven and the earth.

  I write:

if
( sscanf( input_buffer, "%d %d %d", &length, &width, &height )== 3 &&
  sscanf( other_buffer, "%d %d %d", &color, &price, &weight )== 3 &&
  needs_processing( color ))
{ compute_volume( length, width, height );
  compute_something_else( price, weight ); }

^
'---- What I like about this is:

      This is an if statement with two variable constituents:
      an expression and a statement.

      This is the macrostructure.

      The major questions one encounters when reading are:

          - What a kind of entity is this at all?

      And then, having learned that it is an if statement:

          - Where is its expression?

          - Where is its statement?

      And it are exactly the answers to these three questions
      that are each marked with a character in the leftmost column!

      So the type of the entity and its two constituents
      clearly stand out graphically (visually). Albeit in a
      manner not too obtrusive and not wasting lines.

      Now we can compare this with (IIRC, this is code someone
      else wrote):

if (sscanf(input_buffer, "%d %d %d", &length, &width, &height) == 3 &&
    sscanf(other_buffer, "%d %d %d", &color, &price, &weight) == 3 &&
    needs_processing(color)) {
    compute_volume(length, width, height);
    compute_something_else(price, weight);
}

       Here the start and end of the statement are marked in the
       leftmost column. This is also not bad, but the important
       separation between the expression and the statement of the
       if is ?hidden? in the ?center? of this character structure.