Series Clean Code - Formatting

Continue the Clean Code series, today I'll talk about Formatting topic. The Purpose of Formatting are make the code clearly, more clarify. Beside it, the mode of code is very important because code format is also a communication channel, and is the first order of professional developers.

Vertical Formatting

•  Small files are easier to understand than large files.

The Newspaper Metaphor

• Think like writing a good article, you read it from the top down:
  - At the top, the title tells you what the article is saying.
  - The first paragraph summarizes the whole story, hides the details, and brings out the concepts. - As soon as going down the details will be increased.  
• We want the source code to be like an article:
  - The name is simple but clearly explained, the name tells us whether it is in the correct module or not.
  - At the top provides advanced concepts and algorithms.
  - Details will increase as we move downwards.

Vertical Openness Between Concepts

• Openness between concepts >> separate the less relevant things.
• The code is read from left to right, from top to bottom.
• Each line represents an expression or clause, and each group of lines represents a complete thought.
• Those thoughts should be separated from each other by white lines.

 


Vertical Density

• Density >> combine the relevant things.
• Therefore, lines of code that are closely related should appear close together vertically.
• Note that useless comments can ruin this tight link. 

Vertical Distance

• Concepts related to each other should be placed close together.
• Variable Declarations
• Instance variables
• Dependent Functions

Variable Declarations

• Local variables should be placed at the beginning of each function.

• The control variables for the loop should be declared in the loop.

• Declare the variable closer to where it is used. 

Instance variables

• Declare variables at the top of a class.

Dependent Functions

• If a function calls another function, they should be close to each other.
• The called function should be at the bottom of the function call it >> create a flow of source code from high to low.

Horizontal Formatting

• Try to keep each line short, never move right.

Horizontal Openness and Density

• Use white space to link closely related things and isolate the weaker ones.

 
(1) ++ operator is closely related to the variable.
(2) (3) assign operator: explicitly separates left and right = sign.
(5) there is no space between function names and parentheses (because the functions and parameters are closely related to each other).
(4) the space between the parameters because of the separation of parameters.

Horizontal Alignment

• No need to align the column like below:

 


Indentation

• Indent to hierarchical ranges. 

 


Breaking Indentation

• Do not break the indentation rule for short in if statements, short while loops, or short functions.

 


Dummy Scopes

• Do not use the dummy scope in the while or for loop body.

Team Rules

• Each programmer has his own formatting guidelines, but in group work the group's guidelines must be followed.
• A development team should agree on a single format, then each team member should use that formatting => consistency.

See you in next chapter about Classes in Clean Code...