3. Formatting

3. Formatting
Prev		Next

Formatting refers to the indentation, alignment, and use of white space to lay out your program to increase its readability by others.

Consistency is the key to producing readable code. While many can argue to merits of 2 versus 3 spaces of indentation, placement of curly braces, etc., the real key is to adopt a formatting style and keep to it.

Note

In the real world, organizations adopting a standard for formatting increase programmer productivity by reducing variations and trivial decisions among teams of programmers. A uniform code format allows experienced programmers to understand code at a quick glance; they do not need to visually parse the code word by word and operator by operator to see what it does.

Note

A typical piece of code is written once but read many times.

3.1. Indentation and Braces

Use two spaces for indentation to indicate nesting of control structures.

Avoid the use of tabs for indentation. Tabs depend on your system's settings. What works for you may not work for others. Use spaces instead.

Use a syntax-aware editor such as emacs to do the indentation for you automatically.

Be consistent in the placement of opening and closing braces. Their position should correspond to the block levels they delimit.

public class HelloWorld {
  public void greetUser(int currentHour) {
    System.out.print("Good ");
    if (currentHour < AFTERNOON) {
      System.out.println("Morning");
    }
    else if (currentHour < EVENING) {
      System.out.println("Afternoon");
    }
    else {
      System.out.println("Evening");
    }
  }
}

If a block consists of a single instruction, it is permissible to omit the braces:

System.out.print("Good ");
if (currentHour < AFTERNOON)
  System.out.println("Morning");
else if (currentHour < EVENING)
  System.out.println("Afternoon");
else
  System.out.println("Evening");


for (int w = 0; w < with; w++)
  for (int h = 0; h < height; h++)
    for (int d = 0; d < depth; d++)
      a[w][h][d] = 0;

However, if a subordinate block contains more than a single line at the same level, use braces for better readability, even if they are not required:

for (int w = 0; w < with; w++) {
  for (int h = 0; h < height; h++) {
    for (int d = 0; d < depth; d++) {
      a[w][h][d] = 0;
      b[w][h][d] = 1;
      c[w][h][d] = 2;
    }
  }                   // unnecessary, but more readable
}                     // unnecessary, but more readable

if (terminate) {
  // stop here
  break;
}                     // unnecessary, but more readable

3.2. White Space

Use blank lines and blank spaces to improve the readability of your code.

Use blank lines to separate chunks of program code. Chunks are logical groups of program statements (generally 3 to 7 lines in length) and usually preceded with a single-line summary comment. Use one blank line before every program chunk. Use two blank lines before the start of each new method.

Use one blank space

on both sides of binary arithmetic and relational symbols: c = a + b;
after commas
after semicolons in for statements
after keywords for, if, do, while, switch. (Exception: operators that are used like a function, such as this, super or sizeof.)

Do not insert extra spaces

around selection operators: member.data, node−>next, vec[i]
around parentheses
next to a unary operator: *p++ = !a;
before punctuation

Note

While the latter is contrary to French typesetting conventions, keep in mind that we program in English.

3.3. Line Length

Avoid lines longer than 80 characters. When an expression will not fit on a single line of 80 characters, break it according to these general principles:

Break after a comma.
Break before an operator.
Align the new line with the beginning of the expression at the same level on the previous line.

Note

Needless to say that you NEVER put more than one statement onto the same line.

Prev		Next
2. Commenting Conventions	Home	4. Structuring the Code