Date: 2019-09-09

Code creates interfaces. But code itself is also an interface.

For something so important, code readability is shockingly ill-defined. We often present it as a grab bag of rules: Use expressive variable names. When a function gets big, split it into smaller functions. Use standard design patterns.

But we’ve all seen code that follows the rules and is still, somehow, a mess.

We might try to solve this problem by piling on more rules: If variable names are getting extremely long, refactor the underlying logic. When one class accumulates tons of helper methods, maybe it should have been two. Don’t use design patterns in contexts where they don’t fit.

The guidelines turn into a maze of judgment calls, requiring a developer who can pick and choose. In other words, a developer who already writes readable code.

So there’s another piece of the puzzle here. To find it, we’ll need to build a broader picture of readability.

What’s readability for, anyway?

In practice, readability usually boils down to “I like reading it.” This isn’t a great heuristic. Besides being subjective, it gets tangled up in our past experiences with reading.

Unreadable code reads like a novel trying to pass itself off as code. Covered in long narrative comments. Files packed with text, to be read in sequential order. Cleverness for the sake of being clever. Lack of word reuse. The code is trying to be readable, but it’s targeting the wrong kind of readers.

There’s a difference between readability and code readability.

Code creates interfaces. But the code itself is also an interface.

Is code readable when it looks pretty? Looking pretty is a nice side effect of readability, but it’s not that useful. Maybe on the margins, it helps with employee retention. But so does a good dental plan. Plus, everyone has a different opinion of what “looks pretty.” Soon enough, this definition of readability spirals into a vortex of tabs, spaces, braces, camel casing, and the other formatting holy wars. No one will faint upon seeing misaligned arguments, despite the attention they attract during code review.

Is code readable when it generates fewer bugs? Having “fewer bugs” is good, but what’s the mechanism here? The warm fuzzy feelings someone gets when they see readable code? Reading can’t summon bugs, no matter how powerfully the reader is frowning at the code.

Is code readable when it’s easier to edit? The ease of editing sounds like the best reason. Requirements change, features get added, bugs appear, and eventually someone will need to edit our code. In order to edit it without causing issues, they need to understand what they’re editing and how their edits will change the behavior. This gives us a new heuristic: Readable code should be easy to edit safely.

What makes code easier to edit?

At this point, we might feel a compulsion to rattle off rules again. “Code is easier to edit when the variable names are expressive.” Nice try, but all we’ve done is rename “readability” to “ease of editing.” We’re looking for new insights here, not the same rule-by-rule memorization in a fake mustache and wig.

Let’s start by setting aside the fact that we’re talking about code. Programming has been around for a couple decades, a dot on the timeline of human history. If we restrict ourselves to that dot, we’re drawing our ideas from a shallow well.