It is easy to blame the code of people who left, until you’re the one who leaves

This is something I keep repeating. I've been saying it for about 9 years now, when writing software, managing people, coaching people, or just listening to someone vent after a frustrating git blame.

If you've worked on a codebase that's been around for a few years, you know the feeling. You open a file, you think "why on earth did someone write it like this?", and if the person has already left the company, it's very easy to just blame them. They're not here to defend it. The story writes itself.

But code is decisions written down. And decisions are made in a context that gets lost fast. Maybe the conventions were different. Maybe the product vision changed twice. Maybe a junior stepped up when no one senior was available, shipped something that worked, and it stayed because there was never capacity to revisit it. Most likely, there was a good reason. You just can't see it anymore.

The way I usually get people to stop and think is simple. I remind them that one day, they'll be the one who left. Someone will open their code and have the exact same reaction.

That's usually when it clicks.

And this doesn't only apply to code. The same pattern shows up in strategy documents, architecture choices, process decisions, org changes. Someone looks at how things are and wonders "who thought this was a good idea?". Usually, someone who had context you don't have.

Make the "why" findable

Good code communicates, but it rarely communicates the broader why. Why this approach over the alternatives, why now, why these tradeoffs. That context lives outside the code, and it needs a home. Link your code to the ticket. Link the ticket to the decision. Capture the constraints, the alternatives, the reasoning, the business strategy behind it. Write project briefs, RFCs, architecture decision records. If the decision happened in a chat, paraphrase it somewhere more permanent. Make the why live near the work, not just in someone's head.

A dear colleague of mine (hi Sean 👋) once said it would be great to have a historian for a codebase, someone who provides context to people who weren't there when things were built. With approaches like spec-driven development and AI tooling in general, that idea is becoming more realistic. And if we do the work of properly documenting and cross-referencing our decisions, the payoff compounds: AI can actually help us understand why something was written in a specific way. But only if the context is there in the first place.

I also believe we'll spend more and more time thinking about what to build and why, because the how is getting easier. I think that's a healthy shift. In my experience, not enough people zoom out and question why we're building something in the first place. And when more energy goes into the why, documenting the context around our decisions becomes more natural and more important than before.

So next time you find yourself frustrated at someone else's code, assume positive intent. Try to find the context. And if you can't find it, let that be the motivation to leave better context behind in your own work 🤗