Clean Code - 5 Formatting

The Purpose of Formatting

Code formatting is about communication, and communication is the professional developer’s first order of business

Coding style and readability persist, even as the original codes are changed over time because of maintenance and extension needs.

Vertical Formatting

Example of Java projects file length distributions:

What can we see from the graph?

• None have more than 500 lines
• Most of them are less than 200 lines

Smaller files increase the code readability.

The Newspaper Metaphor

From top to bottom, it should be from high-level concepts and algorithms to details and low-level functions.

Vertical Openness Between Concepts

Each line represents an expression or a clause, and each group of lines represents a complete thought. Those thoughts should be separated from each other with blank lines.

Vertical Density

then vertical density implies close association.

Example of "eye-full" codes, which means the reader can understand the codes without moving their eyes too much.

Vertical Distance

Should not make readers spend time searching for where are the codes when they try to understand what the system does.

their vertical separation should be a measure of how important each is to the understandability of the other.

Variable Declarations

Variables should be declared as close to their usage as possible.
Because our functions are very short, local variables should appear a the top of each function.

function getHeadings(): string[] {
    const headings: string[] = [];
    ...
}

Control variables for loops should usually be declared within the loop statement.

for (let i = 0 ; i < names.length ; i += 1) {
    ...
}

Instance variables

should be declared at the top of the class.

the instance variables to be declared in one well-known place. Everybody should know where to go to see the declarations.

Dependent Functions

they should be vertically close, and the caller should be above the callee.

function prepareDinner(): void {

    shopGrocery();
    ...
}

function shopGrocery(): void {
 ...
}

Conceptual Affinity

When some codes want to get closer to each other, it might be because:

• They have a direct dependence
  • Dependent functions
  • variables of a function
• They have similar tasks

class Assert {

    public assertTrue() : void {
        ...
    }
    
    public assertTrueWithMessage() : void {
        ...
    }
    
    public assertEqual() : void {
        ...
    }
}

Vertical Ordering

• A nice flow of codes should be from high level to low level.
• function A call function B, the order of function A and B should be:

function A(): void {

    B();
    ...
}

function B(): void {
 
    C();
    ...
}

function C(): void {    
    ...
}

Horizontal Formatting

The example from the book shows line lengths distribution (seven projects).

• Shorter line is preferred
• Shorter than 120 characters per line is preferred

Horizontal Openness and Density

• Assignment statements
  Have spaces on both sides to indicate two main elements.
  const bigCat: Cat = new Cat();

• Function names and the opening parenthesis
  No space is needed because they mean one thing together.
  function getFood(): void

• Arguments
  Separate with space and comma.
  cookDinner(apple, curry, pork);

• The precedence of operators

  • High precedences stay close to each other (e.g. need to be calculated first).
    return a*b*c + d%2;
  • But most tools give the same spaces now.

Horizontal Alignment

The initial work from the author is not helpful for code readability.

Thus, unaligned declarations and assignments work better.

Indentation

A source file is a hierarchy rather like an outline

Class
space Method
space space Implementation of the method
space space space Containing block
space space space space Block implementation
space space space space space …

This is bad:

Nice:

Breaking Indentation

The author avoids collapsing scopes down to one line:

More readable:

Dummy Scopes

Difficult to find the end ;

Team Rules

Members of a team should follow the same coding style.

Uncle Bob’s Formatting Rules

See the example codes of Listing 5-6 CodeAnalyzer.java in the book.

tags: learn clean code test automation