# 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`