3. Formatting

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.

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

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

Do not insert extra spaces

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: