While discussing ideas about code formatting I’ve seen it usually falls into the everyone does whatever works for them category, meaning it seems like everyone has their own rules.
Let’s see why it is important to look into code formatting and a few points to take into account.
Q: Why should I care?
A: Cross team readability
It’s easier for a team to work together when following a few standards, It’s not about who writes the best code, it’s about working as a single unit.
You will realize you are on the right track the day when you are not able to differentiate within a team among your code and other person’s code.
A: Make it look professional
Nicely formatted code looks professional.
Q: What should I look for?
I had the simple idea of visual blocks, a visual block is meant to group together common ideas and behaviors, when you scan a file for the first time you should get the main idea about what is this file about.
There’s a better way to delve into the topic thanks to a book called Clean Code, so I’m gonna borrow some of the concepts from its Chapter 7 – Formatting:
Vertical openness between concepts
You decide how big your file is, Clean Code offers the newspaper metaphor as a suggestion on how to think about your file. An article in a newspaper is usually composed by different parts. The first few paragraphs outline what the article is about, subsequent paragraphs group together ideas derived on what the previous paragraphs stated.
A group of lines stand for a thought, each thought should be separated from each other using blank lines.
Vertical density
Quoting Clean Code:
Openness separates concepts, density implies close associations
Vertical distance
Quoting Clean Code:
Concepts that are closely related should be kept vertically close to each other.
Vertical ordering
Related concepts should have an order, ordering ways I usually follow:
- Class methods first, instance methods later
- Alphabetically ordered methods
- Public methods first, private stuff later
Horizontal formatting
I’ve talked about this one a lot with friends, quoting from Clean Code:
How wide a line should be?
I tend to stick to no more than 80 chars, others simply write whatever line length as long as they don’t have to scroll, but I mostly strive to answer this:
How wide is a human’s vision span and how it relates to reading big lengthy lines?
Wikipedia’s vision span article says: The field of view that is observed with sufficient resolution to read text typically spans about 6 degrees of arc, which is wide enough to allow a clear view of about five words in a row when printed text at ordinary size is held about 50 centimeters from the eyes.
Did you catch that?
5 words in a row
Of course this may vary on every person, according to some comments on a stackoverflow related topic, books usually stick to around 66 chars per row.
So, there are actually more reasons to keep your lines shorter than larger.
Wrapping up
For me the base guidelines are:
- Strive for cross team readability
- Strive for visual blocks
- Take into account vertical openness, density distance and ordering
- Take into account horizontal formatting
In the end, do whatever feels comfortable for you, if you want to learn more about code formatting or read a few topics related to it, go to Clean Code, or just wait for my next article.
Thank you for reading.
