Designing systems that survive their authors.

Inherited a codebase last spring that had been touched by eleven engineers over six years. The original architect had moved on three jobs ago. The documentation was a 2019 README and a handful of comments that pointed to tickets in a Jira instance that no longer existed. And yet — the system was running. Quietly, reliably, profitably.

That experience reframed something I'd been chewing on for years: the single most valuable property of a codebase is not how clean it is, how fast it runs, or how cleverly it's abstracted. It's whether someone — anyone — can show up tomorrow morning and make a meaningful change without breaking things in surprising ways.

Elegance is a local optimum

We tend to celebrate the engineer who reduces 200 lines to 40 with a beautifully composed abstraction. And we should — sometimes. But often, that 40-line version requires its reader to hold seven concepts in their head simultaneously, infer the data flow from naming conventions, and trust that the implicit contracts haven't drifted.

The clever code I wrote at 28 made me proud. The clever code I wrote at 28 is what 38-year-old me has spent the most time apologizing for.

That doesn't mean every codebase should read like a beginner's tutorial. It means: if you're going to ask the next person to learn a new pattern, the cost of that learning needs to be earned somewhere — in clarity, performance, safety, or expressive power that pays off across many sites of use.

Three things I optimize for now

1. Local readability over global elegance. Can someone understand a function by reading it and the things it directly calls, without chasing four files? If not, I push complexity outward.
2. Boring boundaries. The interfaces between modules should be the dullest, most predictable part of the system. Save your creativity for what's inside them.
3. Documentation that lives next to the code. Not a wiki, not a Notion page — a block comment at the top of the file explaining why this exists. The "what" can be inferred. The "why" cannot.

The compounding cost of cleverness

Every clever abstraction has a half-life. The team that wrote it remembers the constraints that produced it. Six months later, half the team is gone. Eighteen months later, the constraints have changed — but the abstraction hasn't, because nobody quite remembers why it's shaped that way, and touching it feels risky.

Boring code doesn't have this problem. It's legible without context. It invites change rather than punishing it. And in a world where most software outlives the team that wrote it, that's the trait that compounds.

What this looks like in practice

When I review a PR these days, I find myself asking a different set of questions than I did five years ago:

• Could a new hire understand this in their first week?
• If I delete the comments, is the intent still clear?
• Does this introduce a pattern, and if so — is it worth its weight?
• What's the failure mode when this gets misused?

None of these questions are about cleverness. All of them are about survival. The codebases I've watched age the most gracefully are the ones whose authors seem to have asked these questions instinctively, long before I understood why they mattered.

Closing thought

Software is one of the few crafts where you regularly hand your work off to strangers and walk away. The honest measure of your craft isn't how the work looks the day you ship it. It's how the work looks five years later, in the hands of someone you'll never meet — and whether they curse your name or quietly thank you for making their job a little easier.

I write for that person now. It's made me a worse showoff. It's made me a better engineer.