On writing boring software

The code I’m proudest of is code nobody talks about. It does one thing, it’s been doing it for a long time, and nobody has had to open it since. No tricks. A new hire could read it top to bottom and get bored.

That’s the goal. It took me way too long to believe it.

Clever code is a loan

Every clever trick borrows against someone’s future understanding. The metaprogramming that saves forty lines today costs an hour the first time someone wonders where a method comes from, because it isn’t written anywhere. The neat lookup table that folds six cases into one costs a debugging session when case seven shows up and doesn’t fit.

And the person paying the interest usually isn’t me. It’s whoever opens the file at 2am during an outage, with a stack trace pointing into a layer I thought was beautiful.

Boring code doesn’t charge interest. It says what it does. You read it, you’re done.

Boring isn’t lazy

People hear “boring” and think copy paste everywhere. That’s not it. Boring code is often harder to write, because I have to understand the problem well enough to say it plainly.

When I reach for a clever abstraction, it’s usually because I can feel a pattern but can’t name it yet. The abstraction lets me skip naming it. Then the problem turns out to have a different shape than I guessed, and now the abstraction is in the way of the fix.

Three plain if branches, each with a clear condition, look worse. They also describe what’s actually going on.

What survives

Look at software that’s still running after ten years. It’s rarely the one with the fancy metaclass. It’s the one with a thousand small functions that each do the obvious thing. Software lives as long as people can keep changing it, and people can only change what fits in their head.

Every clever bit shrinks the number of people who can safely touch the code. Do that enough and only I can maintain it. That’s not job security. That’s a liability with my name on it.

My test

Before I merge something I’m a little too pleased with, I imagine the reviewer asking “why is this like this?” and I have to answer in one sentence. No “because it’s more general”.

If the honest answer is “because it’s clever”, I write the dumb version and compare. About half the time the dumb version is longer and better. The other half, the clever one stays, because it turned out to be the simple way to describe the problem after all.