Writing Code To Be Read at a Glance

What does writing code that’s easy to read at a glance actually involve? To me, it comes down to thinking about the “shape” of my code. The structure of the code should give you a quick idea of what it’s supposed to do.

An immediate consequence of caring out the shape of your code is that related code looks related and unrelated code looks unrelated—regardless of implementation. How your code looks is a key affordance for guiding the reader’s attention without forcing them to read the code in detail.

Verbosity

Verbose identifiers obscure the shape of your code. This doesn’t mean you should never use verbose names in your code, just that you should be restrained and tasteful. If an identifier comes from far away—a function from a logically distant module, say—giving it a descriptive name can outweigh the downsides.

As an illustrative—if extreme—example, let’s compare three versions of the same logic. Here’s some Java code using BigDecimal:

final BigDecimal result = 
  a.multiply(x.pow(2)).plus(b.multiply(x.plus(c)));

Java does not have operator overloading. If it did¹, the code might look like this instead:

final BigDecimal result = a * (x * x) + b * x + c;

Both of these implement the same mathematical formula:

\[ \text{result} = ax^2 + bx + c \]

This is about as simple as a polynomial gets, but even that wasn’t immediately clear from the first version of the code: you’d have to pay attention to read the sequence of named method calls to understand what was going on. The version with overloaded operators is a real contrast, although it still requires more attention than the math notation. If the first snippet is like reading a paragraph, the second snippet is like reading a short sentence and the math notation is like reading a single word.

With the math notation, we can instantly tell we’re looking at a polynomial just from the shape. The information we care about for polynomials are the terms; the addition and multiplication holding everything together is more like an implementation detail. The math notation reflects this by visually grouping together the information for each term and using an operator (+) as “punctuation” to pull it together. Addition is part of what makes the polynomial a polynomial but, once we know what we’re looking at, it can fade into the background.

Context

People are naturally good at tracking context. We can see this with natural language all the time: the same word or phrase can have somewhat different—or sometimes radically different—meanings in different contexts, but this is so natural that, once people are used to it, they barely notice. What was the last time you thought about how red wine is actually purple, or that, for programmers, “strings” and “threads” have absolutely nothing to do with each other?

Context sensitive meanings aren’t free. The way words in natural languages have different meanings (polysemy) is a real obstacle for early language acquisition. But part of the reason that polysemy is difficult is that native speakers do not even notice they are relying on it! Once you get comfortable in a language—whether a totally different language, or just the jargon and conventions of a new social group—tracking the meaning of words based on context becomes free. The reason natural languages have polysemy is that relying on context takes less mental energy than communicating in verbose, fully-explicit phrases.

We can take advantage of this natural tendency in programming. If I’m working on a module that is implementing an HTTP client for the Stripe, I’m going to be fine using get to mean “send an authenticated HTTP GET request to Stripe”. But in a broader, less Stripe-specific context, I would want to write something like Stripe.get instead².

Plumbing

Some of your code is the “meat” of your expression, the logic that matters for whatever you are doing. The rest is more like plumbing—code that we need to keep everything working but less significant in any particular instance. Think of type conversions, control flow, error propagation, configuration management… Sometimes fixing a bug will hinge on how a specific config value flows into your function but, most of the time, you care far more about what the function does.

Quickly distinguishing plumbing code from logic is key for understanding and navigating code quickly. When you’re scanning through a codebase, you can ignore plumbing code altogether. I’ve found this is where certain “controversial” language features like macros, overloaded operators and control-flow abstractions.³

As an example, using infix operators for plumbing constructs makes the plumbing visually distinct from “normal” identifiers while also giving your code some additional visual structure by naturally organizing the expression up into groups.

After a while, plumbing operators start to fade into the background when you’re scanning through code. Squint a bit, and you start seeing similarities between code that might be doing the same thing in different contexts. Consider the Applicative operators in Haskell: they let us apply functions over values in some functor (like Maybe and IO) in a way that’s immediately reminiscent of normal function application:

f a b c             -- normal function application
f <$> a <*> b <*> c -- over an Applicative

This style also lets us see how operators naturally group code together:

f (a + b) (c * d)
f <$> a + b <*> c * d

Applicative notation might read like line noise to the uninitiated—and, honestly, it’s not exactly the best example of clean plumbing code—but, once you’re comfortable in Haskell, it just melts away. (Which is also 100% true of Lisp’s parentheses! Write enough Lisp and you stop seeing them. It is uncannily like the “I don’t see code” scene from The Matrix.)

Information Content

One perspective I’ve found useful is to think about the minimum amount of information an expression must contain. A polynomial in a single variable, for example, only really needs its coefficients. A web route needs the route, the methods it supports, any variables it takes and the variables’ types.

Anything else is unnecessary from a raw information point of view. We might still need additional code—for plumbing, for structure or just as an implementation detail—but, for thinking about API design, we want to be able to distinguish the core information the code is conveying from everything else. “Everything else” may be useful for organizing our code, but it might also be nothing more than unavoidable—or, depressingly often, completely unforced—boilerplate.

Boilerplate makes code harder to read at a glance.

As a general guide, I try to eliminate more and more of the inessential code as I repeat a particular kind of expression more and more. In extreme cases, a table layout might be the most readable option if you have a whole bunch of structured rows of code repeating.

Good code is, ultimately, a human factors problem. We want to understand how people interact with code—how they read, write, skim, navigate, modify, reuse and repurpose code—and then write and organize our code in a style that makes these interactions as easy and natural as possible.

Writing code to be read at a glance is just part of the story, but it’s something I’ve found useful and important. Code I’ve written keeping this principle in mind just feels lighter. And that, fuzzy as it sounds, makes a real, practical difference to how much time, energy and focus it takes to work on a codebase. Making code skimmable is nowhere near the most important aspect of making code pleasant and effective, but it does matter, and I have not seen people explicitly talking about it.

I don’t have much advice for putting these ideas into action. For me, just realizing that I valued code I could read at a glance and keeping that in mind when I wrote future code was all it took. I quickly developed the right habits and now I don’t have to think about it.