Don’t Make Me Read Your Code!
Imagine a codebase that’s just a handful of lines long. Finding and fixing bugs, and adding new features would be trivial.
But back to reality.
My dev shop has about 2,000 GitHub repositories, each with hundreds, thousands, or even tens of thousands of lines of code. Finding code relevant to the task at hand is hard. Stupid hard. I’m betting your codebase is similarly challenging.
As writers of these vast volumes of code, we should try to make them easier to slog through. We should facilitate code readers in focusing on their project — letting them get right to the point — no dilly-dallying so to speak. And to really focus on something, one must ignore everything else.
James Clear put it this way, “Focus is the art of knowing what to ignore.”
If I can ignore 1,999 of the 2,000 GitHub repositories, and ignore 13,472 of 13,477 lines of code (yes I’m letting you do simple subtraction here), then I can focus on a handful of lines of code. Finding and fixing bugs, and adding new features is now trivial.
Mark’s Law for Code Readability:
Code is readable in proportion to any I don’t have to read.
As software engineers, let’s try to write code that helps readers easily find and focus on their thing not ours, and safely ignore everything else.
Abstractions, cohesive components, single-responsibility microservices, whitespace, good names, smaller functions, testability, guard clauses — all play a helpful role in minimizing the amount of code necessary to be read.
Complex intermingled (and mangled) logic, nesting, coupling, duplication, and the rest of the infinite set of bad ways to code— all tend to maximize the amount of code that needs to be read.
Don’t make me read your code. Please.
Precisely because we have so many subjective ways to decide if code is more or less readable, it’s great to have this solid, quantifiable rule. An example: Code that lets me skip reading 50 lines of code is 10x more readable than code that lets me skip only 5 lines. And infinitely more readable than code that makes me understand everything.
Deleted code is the ultimate win here. It’s the easiest of all to skip. It’s skipped by default. The next best thing is to abstract code away. Stick it in a function or a module. Put it “below the fold” so it’s less likely anyone would have to look at it. “Oh, that’s the part that integrates with Sales, so that’s not what I’m looking for,” or, “That function calculates the scores, I can skip over that.”
An experiment to try before your next PR:
- Use Google’s random number generator to pick 3 random lines of code in your change set.
- Go to the nearest meaningful line of code and try to determine how much surrounding code must be read to understand that line. Any variables here? Where were they set, modified? What do they mean? Am I setting a variable or returning a value here? Where and how is it used? Is this line nested? If so, what logic got me here? Any variables used in that logic? Where were they set, modified? You get the idea.
- Modify the code to minimize the need to read other code to understand it — maximize skip-ability — maximize the code I don’t have to read.
- Compare the before/after code. I’m betting pretty strongly that you’ll find the “after” code is better. It’ll be better in proportion to the amount of code I don’t have to read. You’ll find that Mark’s Law holds.
Conclusion
Not having to read your code makes me more productive. I hope that is self evident.
I’ll read a little bit of your code, a handful, the part that’s relevant to my project. Help me be able to find it quickly and focus on my task at hand — safely ignoring everything else.
The amount of code that you wrote that I don’t have to read is a key indicator of the readability, maintainability, and quality of your code.
No matter how great you think it is, please don’t make me read your code.
