My Notes from Clean Code Book: Formatting
In this article we will continue with chapter 5 which talking about Code Formatting:
Code formatting is the process of arranging code in a readable style. It involves things like indentation, spacing, line breaks, naming conventions, and comments.
Imagine a book. A well-formatted book has clear and concise writing, with proper punctuation and grammar. The paragraphs are spaced evenly, and the text is justified (aligned to both the left and right margins). This makes the book easy to read and understand.
well-formatted code is like a well-formatted book. It is easy to read and understand because it is formatted in a consistent and readable style.
Why Code Formatting is important ?
- Readability: Code that is formatted in a consistent and readable style is easier to read and understand. This makes it easier to maintain and debug.
- Understandability: Code that is well-formatted is easier to understand, even if you are not familiar with the codebase. This makes it easier to collaborate with other developers and to onboard new developers.
- Maintainability: Code that is well-formatted is easier to maintain, because it is easier to read and understand what the code does and why. This makes it easier to fix bugs and to add new features.
Let’s take a poorly formatted Example then refactor it to be formatted:
poorly formatted version of the function:
func calculateAreaOfRectangle(length: Int, width: Int) -> Int {
// Calculate the area of the rectangle.
let area = length * width
// Return the area of the rectangle.
return area
}This function is poorly formatted because:
- The code is not indented, which makes it difficult to read and understand the structure of the code.
- The code is not spaced evenly, which makes it difficult to read.
Here is a well-formatted version of the function:
func calculateAreaOfRectangle(length: Int, width: Int) -> Int {
"""
Calculates the area of a rectangle.
Args:
length: The length of the rectangle.
width: The width of the rectangle.
Returns:
The area of the rectangle.
"""
// Calculate the area of the rectangle.
let area = length * width
// Return the area of the rectangle.
return area
}what we do to refactor this function to be well-formatted?
- Added a comment to the function explaining its purpose.
- Used a more consistent whitespace style.
- Added a blank line between the function parameters and the function body.
- Aligned the function parameters and the function return value.
- Added two blank lines after the function body.
Types of Code Formatting:
There are two main types of code formatting: vertical formatting and horizontal formatting.
1- Vertical Formatting:
Vertical formatting is the practice of arranging code elements in a way that makes them easy to read and understand from top to bottom. It is in contrast to horizontal code formatting, which focuses on arranging code elements in a way that makes them easy to read and understand from left to right.
There are a few key principles of vertical formatting:
- Vertical openness: Vertical openness refers to the use of blank lines to separate different concepts in the code. This makes it easier to scan the code and to find the different parts of the code.
- Vertical density: Vertical density refers to the grouping of related code lines together. This makes it easier to see the relationships between the different parts of the code.
- Vertical ordering: Vertical ordering refers to the order in which related code concepts are placed in the code. This can be used to convey the logical flow of the code and to make the code more readable.
Example of Vertical Formatting:
func calculateAreaOfRectangle(length: Double, width: Double) -> Double {
"""Calculates the area of a rectangle.
Args:
length: The length of the rectangle.
width: The width of the rectangle.
Returns:
The area of the rectangle.
"""
return length * width
}
// Example usage:
let area = calculateAreaOfRectangle(length: 10, width: 5)
print(area)This code is well-formatted because:
- The code is divided into small files.
- The code concepts are arranged from top to bottom.
- Blank lines are used to separate concepts.
- Related code lines are grouped together.
- Variables are declared close to their usage.
- Code blocks are aligned vertically.
Let’s take another example of vertical formatting:
class Person {
"""A class to represent a person."""
let name: String
let age: Int
init(name: String, age: Int) {
self.name = name
self.age = age
}
func greet() {
print("Hello, my name is \(name) and I am \(age) years old.")
}
}
// Example usage:
let person = Person(name: "Alice", age: 25)
person.greet()This code is also well-formatted because:
- The code is divided into small files.
- The code concepts are arranged from top to bottom.
- Blank lines are used to separate concepts.
- Related code lines are grouped together.
- Variables are declared close to their usage.
- Code blocks are aligned vertically.
2- Horizontal Formatting:
Horizontal formatting is the practice of arranging code elements in a way that makes them easy to read and understand from left to right. It is in contrast to vertical code formatting, which focuses on arranging code elements in a way that makes them easy to read and understand from top to bottom.
There are a few key principles of horizontal formatting:
- Line width: Lines of code should be kept short, typically around 80–120 characters wide. This makes it easier to read the code without having to scroll horizontally.
- Whitespace: Whitespace should be used to align code elements and to group related code elements together. This makes the code more readable and easier to scan.
- Indentation: Indentation should be used to show the logical structure of the code. For example, code blocks should be indented relative to the code that contains them.
Example of Horizontal Formatting:
func calculateAreaOfRectangle(length: Double, width: Double) -> Double {
"""Calculates the area of a rectangle.
Args:
length: The length of the rectangle.
width: The width of the rectangle.
Returns:
The area of the rectangle.
"""
return length * width
}
// Example usage:
let area = calculateAreaOfRectangle(length: 10, width: 5)
print(area)This code is well-formatted because:
- The lines of code are kept short.
- Whitespace is used to align code elements and to group related code elements together.
- Indentation is used to show the logical structure of the code.
Let’s take another example of horizontal formatting:
class Person {
"""A class to represent a person."""
var name: String
var age: Int
init(name: String, age: Int) {
self.name = name
self.age = age
}
func greet() {
print("Hello, my name is \(name) and I am \(age) years old.")
}
}
// Example usage:
let person = Person(name: "Alice", age: 25)
person.greet()This code is also well-formatted because:
- The lines of code are kept short.
- Whitespace is used to align code elements and to group related code elements together.
- Indentation is used to show the logical structure of the code.
Fortunately in the modern IDE we Don’t waste time manually formatting our code. By on click we can formatting our code
In summery:
Formatting is an important part of writing clean code. By following simple formatting guidelines, you can write code that is easier to read, understand, and maintain.
