I wrote a class once that handled bulk database upserts with optimistic locking. Inserts and updates in one query, concurrency control via MySQL session variables, column signature grouping so it could dynamically build different SQL shapes depending on which fields you were touching. I looked back on it a few months later and… while it was working… it was horrifically over-engineered and, to put it mildly, “a lot.” The kind of code where every line is load-bearing and you feel briefly brilliant for having written it, right up until you need to change something and realize you’ve built a trap for yourself.

We needed to change the locking behavior, and I opened the file and could not follow my own logic. I’d used a MySQL session variable to count successful updates inside the ON DUPLICATE KEY UPDATE clause, because MySQL doesn’t have RETURNING, so you can’t just ask “hey, which rows did you actually touch?” like a normal database. You have to hack around it with session state. (Postgres people, I know. I KNOW.) The insert path and the update path were fused together in a way that made each one impossible to reason about without understanding the other. I had to trace through the whole thing end-to-end just to figure out where to add an if statement. The class was 500 lines, most of them doing real work, and I couldn’t safely touch any of them.

Here’s the part I actually want to talk about, because the “don’t write clever code” sermon has been given plenty of times (including, now, by me).

My first move wasn’t to simplify it. It was to make it smarter. There was an intermediate PR where I added a variance-based routing layer that decided whether to use direct SQL or the session-variable path depending on how similar the update patterns were. Which, yes, means I responded to “this is too complex” by adding a decision tree. There was an incident. I learned.

I don’t think that was a fluke. Clever code sets a bar, and once it’s there, the simple rewrite feels like a downgrade… like admitting the first version was a mistake, which it was, but nobody wants to open that PR. So you patch cleverness with more cleverness, because at least that looks like progress. The trap isn’t writing the clever thing once. It’s that the clever thing makes the boring fix feel beneath you.

Eventually someone (me, humbled) split inserts and updates into separate paths… INSERT IGNORE for new rows, plain UPDATE for existing ones. Boring. Obvious. The kind of code you’d write if you weren’t trying to impress anyone. A later PR optimized the update path properly, once we had metrics showing it was actually slow, rather than pre-optimizing based on vibes. The end result was faster, easier to test, and significantly less clever. Everyone who touched it afterward could modify it without re-deriving the whole thing from scratch.

That original class wasn’t wrong, exactly. It worked. The tests passed. But it was written at the limit of my own cleverness, which meant that debugging it required being smarter than the person who wrote it. And the person who had to debug it was also me, just dumber and with less context. Not a great setup. Brian Kernighan said it in The Elements of Programming Style back in 1978:

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you’re as clever as you can be when you write it, how will you ever debug it?

The same thing happens at the scale of a single line. Here’s a cousin of the column-signature trick from that class, grouping rows by which columns they set:

by_signature = {
    sig: list(group)
    for sig, group in groupby(rows, key=lambda row: tuple(sorted(row)))
}

And the boring version:

by_signature = defaultdict(list)
for row in rows:
    signature = tuple(sorted(row))
    by_signature[signature].append(row)

The first one looks great. One expression, no mutation, very functional, very impressive in a code review. It’s also wrong. groupby only groups consecutive items, so when a signature shows up again later in the list, the comprehension quietly overwrites the earlier group. Rows just… vanish. No error, no warning. It passes every test where the fixtures happen to be sorted, which test fixtures usually are, and then drops data in production where nothing is. The boring version has no trick to get wrong. You’re saving keystrokes and spending correctness, and the next reader (who is probably tired) has to know an obscure itertools footnote to notice.

That matters more than it sounds like it should. There was a study out of Zhejiang University that tracked professional developers and found they spend roughly 58% of their time on program comprehension. Reading, not writing. So when you optimize for writing speed at the expense of reading speed, you’re making the majority of the work harder. Great job, you.

Sandi Metz has a line I think about a lot: “duplication is far cheaper than the wrong abstraction.” It cuts against stuff we treat as gospel. DRY, KISS, YAGNI… we learn these as laws, engrave them on our laptops, and never stop to notice that they contradict each other all the time. DRY says don’t repeat yourself; Metz says the wrong abstraction (which you built because of DRY) is worse than the duplication it replaced. KISS says keep it simple, but the person who wrote the clever version almost always thinks it’s simpler. I certainly did. My upsert class started as one clean idea and calcified into a thing nobody could modify without understanding the whole thing, and the fix was to inline it back into boring, duplicated paths.

Are there cases where cleverness is warranted? Sure. The inner loop of something that runs a million times a second. But even then, the clever code should come after the simple version works, after you have metrics proving you need it, and with comments explaining what it does and why. My upsert class would’ve been fine as two simple queries from day one. I made it one query because I could, not because I had to.

Dan McKinley has a talk called “Choose Boring Technology” that I’ve internalized more than I probably realize. His point is about technology choices at the organizational level… don’t adopt Cassandra because it’s exciting, use Postgres because you already know how it fails… but it scales down to individual lines of code just fine. Boring has known failure modes. That’s the whole feature.

The next person to touch your code doesn’t need your abstraction to be elegant. They need to find the line that’s wrong, understand why it’s wrong, and fix it without breaking something else. That’s it.

Write boring code.