In 2009, a small team at Etsy inherited a PHP codebase that had grown without discipline for years. Functions did six things. Variables were named after their authors’ initials. Business logic lived inside view templates. The code worked, mostly, but nobody could agree on what it actually did. Onboarding a new engineer took weeks just to reach productive confusion.
Etsy’s engineering team made a decision that looked counterproductive at the time: they slowed down to write code that anyone could read. Meaningful variable names. Functions that did one thing. Comments that explained why, not what. The velocity metrics got worse before they got better. Senior engineers who could navigate the old maze resisted. The new code took longer to produce.
But something unexpected happened when requirements changed, as they always do. The readable code could be deleted.
The Setup
Etsy in 2009 was preparing for serious growth, and its engineering culture was in the middle of a documented, public transformation. The company would later become famous for its continuous deployment practices, shipping code to production dozens of times per day. What made that possible wasn’t just tooling or process. It was the decision to treat the codebase as something that would be read and discarded as often as it would be executed.
The conventional wisdom at the time was that clever code was good code. Brevity was equated with skill. The programmer who could accomplish in ten lines what a junior engineer needed fifty to express was celebrated. This produced systems that were impressively compact and practically unmaintainable. Clever code, it turns out, is almost impossible to delete safely. You can’t remove what you can’t fully understand, so it accumulates.
The Etsy team wasn’t alone in this realization, but they were unusually public about the tradeoff they were making. Their engineering blog documented the friction honestly. Readable code required more keystrokes, more deliberate naming, more explicit structure. It felt like going slower. On a per-feature basis, it was going slower.
What Happened
The payoff appeared during the periods between shipping. When a feature needed to be changed, the readable version could be modified by anyone who hadn’t written it. When a feature needed to be killed entirely, it could be removed without weeks of archaeology. The codebase stayed lean in a way that the previous one never had.
This is the asymmetry that the clever-code philosophy misses. Writing code is a one-time cost. Reading code is a recurring cost. Every engineer who touches a system after you will read your code. Every debugging session, every code review, every onboarding conversation is a withdrawal from the account you funded when you wrote something comprehensible. Clever code charges those withdrawals at a premium.
Deletion is the extreme case. When Etsy decided to sunset features, the readable codebase let them do it cleanly. Dead code removed, dependencies untangled, surface area reduced. The alternative, which any engineer who has worked in a mature codebase will recognize, is that you never quite delete anything. You comment it out. You wrap it in a feature flag and forget to remove the flag. You leave it because the cost of understanding what removing it would break is higher than the cost of carrying it.
This is how codebases become archaeological sites. Layers of decisions, none of which can be safely excavated.
Why It Matters
The lesson extends well beyond Etsy or PHP. Any team that has adopted aggressive deletion as a practice discovers the same prerequisite: you can only delete what you understand.
Amazon’s internal culture around “working backwards” documents has a similar structure. Writing a press release before building the feature forces clarity about what the feature actually does. The document is frequently thrown away. That’s the point. The act of making something legible prepares it for the bin. Code works the same way.
The teams that write the most readable code are often the teams that ship the leanest products. There’s a causal arrow here, not just a correlation. When deletion is cheap, you try things. When deletion is expensive, you carry everything forever and the codebase grows into something nobody fully understands. Deleting a feature is harder than building one, but the difficulty is mostly a function of how legible the original implementation was.
The software industry has spent years optimizing for the act of writing code. Autocomplete, AI assistants, boilerplate generators. All of it reduces the cost of production. Very little of it reduces the cost of comprehension, because comprehension is fundamentally a human problem. A function that generates in three seconds by a language model still has to be read, understood, and eventually removed by a person.
What We Can Learn
The case for readable code isn’t sentimental. It’s economic. The argument isn’t that code should be pretty or that naming conventions matter because they signal professionalism. The argument is that the total cost of a codebase includes every hour spent reading it, debugging it, and attempting to remove parts of it. Clever code externalizes those costs onto future engineers, and future engineers are frequently you.
Etsy’s transformation is instructive because the team was honest about the short-term cost. There was no trick that made readable code write itself faster. It required more thought per function, more discipline per variable name, more explicit structure per module. The payoff was asymmetric and delayed. That’s why most teams don’t do it. The person who bears the cost of writing clearly is often not the person who captures the benefit of reading clearly.
This is the organizational problem underneath the technical one. Teams that optimize for individual velocity produce codebases that slow down collective velocity. The engineer celebrated for shipping fast leaves behind code that takes the next three engineers twice as long to modify. The measurement systems that would reveal this rarely exist.
The teams that get this right treat legibility as a form of ruthless pragmatism, not aesthetic preference. They write code that can be deleted because they know it will be deleted. Everything eventually needs to change. The only question is how much it will cost when it does.
