The Real Reason Your Code Gets Rewritten
Why code that works for reasons you can't explain is a bigger problem than a bug, and why the real audience for your code was never the computer.
Have you ever shipped code that worked, and you had no idea why?
Not code that broke, that's normal. Code that passed, and you still don't know which of the three things you tried actually fixed it. That's the more dangerous version of the same problem, because nothing forces you to go back and find out.
You Can't Fix What You Never Understood
If you don't know why your code works, you have no way to fix it when it breaks, other than guessing again. Call it a rule: understanding comes before repair, every time.
Most teams don't notice this until the pressure is already on. A bug shows up, it's urgent, and the person fixing it opens code they don't remember writing. They search for a cause with no test coverage and no notes, under a deadline, and eventually someone says the sentence every team has heard:
"It'd be faster if I just rewrote it."
That sentence is not really about the code's quality. It's an admission that the code never explained itself, so the only way back in is to start over. Do that enough times across enough teams, and you get an industry where a huge share of engineering budget goes to rebuilding things that already worked once.
The Work You Never Wrote Down
Say you're checking whether a user's subscription is active before showing a feature:
if (isSubscriptionActive(user)) {
unlockPremiumFeature(user);
}No else. Before you deleted it, you mentally walked through every case, expired, cancelled, trial, and confirmed there was nothing to do in any of them. That reasoning was real work.
None of it is in the code. Six months later, someone hits a bug in this exact feature and finds this if statement staring back at them. Was the missing else intentional, or did whoever wrote it just not think about the other cases?
There's no way to tell from the code alone. So they redo the same analysis you already did, under worse conditions: no memory of the decision, a deadline, and the nagging fear that the missing branch is the actual bug.
One comment would have closed that gap:
if (isSubscriptionActive(user)) {
unlockPremiumFeature(user);
}
// No else: expired, cancelled, and trial users all fall through
// to the default free-tier view rendered further up this file.The comment doesn't explain what the code does, the code already shows that. It explains the part that only existed in your head: which cases you considered, and why none of them needed handling.
Code Is a Suggestion, Not an Instruction
There's a second habit that makes this worse: writing code for the computer instead of the next person who opens the file.
Picture a shipping-cost calculation:
const total = baseRate + extra * multiplier;Someone adds parentheses to make the order of operations obvious:
const total = baseRate + (extra * multiplier);A linter flags it: unnecessary parens, remove them. Technically true, the computer already knows multiplication runs before addition. But the computer was never confused. The person reading this file six months from now might be.
That linter rule optimizes for the compiler's needs, not the reader's. And the compiler has less riding on your specific syntax than you'd think: there are infinitely many ways to write a program that produces the same output, and the version you pick is only ever a suggestion to the engine underneath.
The classic example is writing i++ instead of ++i in a loop because a benchmark once claimed it saves a register. Modern engines don't execute your loop literally. They compile it, optimize it, sometimes rewrite it entirely. The register you were "saving" never existed the way you imagined.
So if your specific syntax barely affects what the machine does, but it entirely determines whether the next developer understands you, the real audience for your code was never the computer. It was always the next person to open the file.
The 70% Nobody Optimizes For
Studies on how developers actually spend their day back this up: something like 70% of coding time goes to reading code, not writing it. The average line of code that gets committed and survives is a small fraction of what actually gets typed that day, most of it gets deleted, rewritten, or replaced before it ships.
Every tool and framework release still gets sold the same way: fewer lines to write, faster to type. Almost nothing gets marketed on how much easier it is to read six months later. That's backwards, given where the time actually goes.
Code must be read before it can be written. There's no such thing as write-only code, code you produce and never have to revisit, explain, or hand off. If it's not readable, it doesn't survive, no matter how clever it was on day one.
Six Minutes, Every Hour
The fix isn't a heavier process, it's a habit: take about six minutes out of every hour spent writing code, and spend it rereading what you just wrote.
Ask one question: if you had to explain this to someone new tomorrow, what would confuse them first?
This isn't a "nice to have" you skip when the deadline is tight.
One minute spent making a decision clear today saves hours of rebuilding it later. That's the actual trade: a small, known cost now, against a much bigger, unpredictable one down the line. And it doesn't pay off once, it pays off every single time someone else reads that code.
Skipping it doesn't save time. It just hands the cost to whoever inherits the code next, at a much higher price.
Every technique in this series makes the same trade: a little more typing now, for code that says what it means instead of making the reader guess. Readable code was never the slower option. It's the version that survives.
That's the lens for the rest of this series. Next up: why JavaScript keeps changing at all, and why almost every recent feature exists to make code say more while asking less of the reader.
Keep reading