After 25 years in the IT industry, I've watched this mistake quietly derail more careers than almost anything else.
They don't teach the real world in bootcamps. Get 25 years of production-grade experience on my YouTube: 🛠️👉 https://www.youtube.com/@lessonsfromproduction
You're looking at a piece of code. It works. It's been in production for two years. The variable names are bad, the abstractions are wrong, it violates three things you learned last month.
And you think — I'll just clean this up real quick.
That sentence has killed more engineering timelines than almost any bug ever written.
The engineers who fall into this trap aren't careless. They're the ones who care most. Good taste. Read the books. High standards.
But caring about code quality and knowing when to act on it are completely different skills. Nobody teaches you the second one.
The Lie the Industry Tells You
Good engineers write clean code. Therefore, spending time making code clean is what good engineers do.
Enough truth in it to be dangerous.
The books reinforce it — Clean Code, Refactoring, The Pragmatic Programmer. All brilliant. But read early, without context, they quietly teach the wrong lesson: that clean code is the output your job demands.
It isn't.
Your job produces working software that delivers value. Clean code is a tool toward that end — not the end itself.
Then there's the performance review problem. Shipping features is visible. Refactoring is invisible — until something breaks, at which point it's your fault. Nobody says this out loud. But you feel it.
So some engineers overcorrect. They hold the codebase to standards it doesn't need to meet yet, slow the team down trying to "do it right," and are confused when they don't get recognised for it.
Others undercorrect — carrying debt forward until the system is genuinely unmaintainable, then confused when they can't ship anything.
Both traps come from the same mistake: confusing the tool with the goal.
The Core Insight Senior Engineers Don't Talk About
Here's the real skill that separates senior engineers from everyone else:
It's not writing cleaner code.
It's knowing which code deserves to be clean — and when.
| Less Experienced | Senior | |
|---|---|---|
| Optimises for | Code quality in isolation | Cost-to-value ratio of the change |
| Focuses on | This file, this function, this abstraction | Team momentum, shipping cadence, trust |
| Asks | "Is this code good?" | "What problem does this refactor solve, and is now the right time?" |
The senior version doesn't say never refactor. It says: have a reason — one that maps to a real cost, at the right moment.
Because a lot of messy code is messy for a reason. It's been through a hundred business decisions, edge cases, legal requirements, 2am fires. It doesn't look like the textbook because it didn't come from the textbook.
Before you rewrite something, you need to understand it well enough to replicate its behaviour exactly — including the bugs customers have learned to work around. That's a much higher bar than "I can see how to make this cleaner."
A War Story I'm Not Proud Of
Three years into my career, I made a mistake I want to tell you about.
We had a payment processing module. Genuinely messy — procedural, long functions, inconsistent naming. Written fast under deadline pressure by someone who'd since left. I understood it well enough to navigate it. And I had a two-week window with low feature demand.
I pitched the refactor to my lead. He was hesitant. I pushed. He said okay — keep it scoped.
I did not keep it scoped.
Three weeks in: a partially rewritten module, an incomplete test suite, and edge cases I didn't understand because I hadn't dealt with them live. A product deadline landed. I had to freeze it halfway through. We now had two patterns in the same module — the old one and the new one — which was harder to read than the original.
My lead spent three hours untangling it before the release. He didn't say much. He didn't need to.
The lesson wasn't don't refactor. It was this:
I had mistaken my desire to improve the code for a reason to change it. Those aren't the same thing.
3 Upgrades That Will Change How You Think
Upgrade #1 — Change the Question
Stop asking:
"Is this code clean enough?"
Start asking:
"What pain is this messy code causing, right now, concretely?"
Is it slowing feature development? Causing bugs? Blocking new engineers from getting productive? Those are real reasons.
If the answer is "it offends me aesthetically" — that's a feeling, not a reason. It might become one. Write it down, flag it, and come back when you have a concrete trigger.
Upgrade #2 — Change the Time Horizon
The question isn't just "is this a good refactor?" It's:
"Is this the right refactor, at this moment, in this codebase's life?"
Code in active experimentation doesn't need the same standards as settled, battle-tested code. If the business is still figuring out the product direction, the right architecture doesn't exist yet — so imposing one now means refactoring again in six months.
- High leverage: stable, high-traffic, well-understood code
- Low leverage: volatile code that might be thrown away
Refactoring the first category is a genuine investment. Refactoring the second is usually just waste dressed up as craftsmanship.
Upgrade #3 — Change the Incentive Lens
Before any refactor, ask: who carries the risk if this goes wrong?
Be honest with yourself. Are you refactoring because it's the right call — or for the intellectual satisfaction of a cleaner system? Both motives are human. Only one should get greenlit.
Then ask who benefits:
- If you're the only engineer who touches this code and you'll be measurably faster after — that's a real return.
- If three teams share it and the refactor triggers a three-week integration effort — the benefit needs to be proportional to the blast radius.
How to Push Back Without Getting Ignored
If you genuinely believe a refactor is necessary and your lead is pushing back, don't frame it as "the code is messy."
Frame it as risk.
"This module is the source of 40% of our bugs this quarter. If we don't address the underlying structure, we keep paying this cost every sprint."
Quantify the cost of inaction. Make the business case. That's a senior engineer talking — not someone who wants their code to look nice.
The Identity Reframe
Next time you're sitting with messy code — before you open a branch and start cleaning — pause.
Ask yourself three questions:
- What specific problem does this refactor solve?
- Is that problem costing us right now?
- Am I the right person to solve it, at this moment, with this scope?
If you can answer all three clearly — go. Scope it, timebox it, ship it.
If you can't — write it down and keep moving.
You've been trying to become better at writing clean code.
The real upgrade is knowing when clean code is the job.
The refactoring trap isn't that engineers clean too much or too little. It's that they make the decision with their gut instead of their judgment.
Build the judgment.
Note: This article was written with AI assistance to help structure and articulate 25+ years of real-world engineering experience. All examples, insights, and methodologies are drawn from production systems and lived experience.
Top comments (0)