On writing boring software

The code I’m proudest of is code nobody has mentioned. It does one thing, it has done it for two years, and no one has had to open it since. There’s no trick in it. A new hire could read it start to finish and be bored.

That’s the goal, and it took me an embarrassingly long time to believe it.

Clever code is a loan

Every clever solution borrows against future understanding. The metaprogramming that saves forty lines today costs an hour the first time someone has to trace why a method exists that isn’t written anywhere. The dispatch table that elegantly collapses six cases costs a debugging session when case seven doesn’t fit and someone has to work out whether it was excluded deliberately.

The interest compounds because the person paying it isn’t you. It’s whoever opens the file at 2am with a production incident and no context, holding a stack trace that points into a layer of indirection you thought was beautiful.

Boring code has no interest payments. It says what it does. You read it top to bottom, you’re done.

Boring is not the same as bad

This gets misread as an argument for sloppiness, or for copy-paste over abstraction. It isn’t. Boring code is often harder to write than clever code, because you have to understand the problem well enough to state it plainly.

Clever solutions usually come from an incomplete understanding. You reach for the abstraction because you can feel a pattern but can’t name it yet, and the abstraction lets you avoid naming it. Then the shape of the problem turns out to be different from the shape you guessed, and the abstraction becomes a wall between you and the fix.

The boring version demands you name the thing. Three explicit branches, each with a clear condition, is worse-looking code and a better description of reality.

The systems that survive

Look at what’s still running after a decade. It isn’t the framework with the elegant metaclass; it’s the one with a thousand functions that each do the obvious thing. Software survives because people can keep changing it, and people can only change what they can hold in their head.

Every clever mechanism reduces the number of people who can safely touch the system. Do it enough times and you’ve built something only you can maintain, which is not job security, it’s a liability with your name on it.

The test I use

Before merging anything I’m pleased with, I ask whether I’d be comfortable if the reviewer’s only comment was “why is this like this?” and I had to answer in one sentence without saying “because it’s more general” or “because it handles the case where”.

If the honest answer is that it’s clever, I rewrite it as the dumb version and compare. About half the time the dumb version is longer and better. The other half, the clever version survives because it was actually the simple description of the problem, not decoration on top of it.

Boring is not a ceiling on ambition. It’s what ambition looks like once you’ve stopped writing for an audience.