Best Practices, Byte-sized
Ron’s Clean Code Tidbits: Readability
As a software developer for 15+ years, I’ve often been amazed at the level of technical debt in production code.
And this isn’t just little throwaway projects for small startups. It’s common in multi-million dollar, enterprise-level codebases as well.
And while poor readability is just a part of tech debt, it’s an important one.
When code isn’t as readable, it easily becomes:
- More difficult to reason about — in part since it demands more attention at the level of minutiae (just to figure it out), leaving less cognitive bandwidth to think in higher-level terms;
- A constant (and fatiguing) exercise in mental mapping, between non-intuitive names and the actual concepts they represent;
- Easier to create bugs … and more difficult to find them;
- A hindrance to velocity, for both the team and the company;
- More frustrating for the team to work with (and potentially, even a contributor to burnout).
Coding in Style
“Clean code is simple and direct. Clean code reads like well-written prose.”
— Grady Booch
Knowing the importance of good readability, I used to write detailed coding style guides that ran a couple of dozen pages. They were infused with inspirational quotes, fun illustrations, and numerous examples of best practices tailored to the specific project and team.
More recently, though, I’ve been able to whittle that down to just one page.
How?
First rule of coding style
➨ Use a linter.
Debates about spacing and other simple formatting issues can be tedious and awkward, and clutter up pull request discussions.
Not to mention, they’re unnecessary.
A team should be able to define a set of formatting rules, and then stick with them. And then save their valuable discussion time for other things.
[Note: Make sure your linter doesn’t arbitrarily reformat large amounts of existing code. That would mean a potentially huge loss in valuable metadata. Instead, configure the linter to apply automatic formatting only to new files.]
‘Nuff said.
Second rule of coding style
➨ This little gem:
The Fundamental Theorem of Readability
“Code should be written to minimize the time it would take for someone else to understand it.
What do we mean by this?
Quite literally, if you were to take a typical colleague of yours, and measure how much time it took them to read through your code and understand it, this ‘time-till-understanding’ is the theoretical metric you want to minimize.”
— The Art of Readable Code
I find this simple and brilliant.
It also takes the place of many examples I used to list out in all those pages of a coding style guide.
By contrast, some might argue that code should be written to be the most “efficient” (akin to how that concept is often taught in computer science class). But in practice, that often seems to translate into: overly-terse, cryptic, or non-standard naming conventions; missing function- or class-level comment blocks; cramming multiple operations into fewer lines of code; use of obscure, non-intuitive constructs that offer some theoretical performance advantage (though inconsequential in context); and more.
And while these may seem like minor issues when looking at a small section of code, those habits DON’T SCALE WELL over thousands of lines.
Bear in mind: there’s actually more than one type of “efficiency.”
How about the efficiency of people’s time and energy on the team?
What if they spend valuable cycles scratching their heads, trying to decipher obscure coding? (Even worse, what if it’s long after the original author has left the project, and isn’t around to explain it?)
“Any fool can write code that a computer can understand.
Good programmers write code that humans can understand.”
— Martin Fowler
And remember:
Code is read more often than it is written.
So if we’re really trying to optimize for efficiency, it should generally be that of people reading (rather than writing) that code.
Good coding style means better communication with current and future devs — and that begins with seemingly-trivial things like our choices of method and variable names, legible and consistent formatting, and more.
All of which help reduce that “time-till-understanding.”
And finally, it also suggests writing code that’s simple, rather than “clever.”
After all:
“Premature optimization is the root of all evil.”
— Donald Knuth
(Besides, the compiler can be far more clever in optimizing for execution than you or I will ever be.)
➨ So make The Fundamental Theorem of Readability your friend.
It may be the only coding style guide you need. 😁
Extra credit:
Does each part of your code have a Single Responsibility?
