When to Refactor and When to Rewrite

What you actually need to know

• Refactoring changes the structure without changing the behavior. Rewriting changes both.
• Most code that engineers want to rewrite can be refactored. The instinct to rewrite is often about comfort, not cost.
• The rewrite is justified when the cost of maintaining the existing code exceeds the cost of replacement within eighteen to twenty-four months.
• Tests before refactoring, not after. You need the safety net before you move the furniture.
• Scope creep kills refactors. Define the module boundary before you start and hold it.
• The strangler fig pattern is the right path for any system that handles live traffic.

The core argument

The question of refactor versus rewrite comes up in almost every engineering team that has been building for more than two years. The codebase has accumulated decisions that made sense at the time and do not make sense now. Someone on the team says "we should just rewrite this." The conversation that follows is usually emotional rather than analytical.

The emotional pull toward rewriting is understandable. The existing code has scars. Every engineer who has worked on it carries the memory of the bugs it caused and the workarounds it required. The idea of starting clean, without those scars, feels like relief. The problem is that rewrites are almost never the relief they promise. The new code will have its own scars. The team will carry knowledge about the problem domain that only existed in the old code. The schedule will slip. The business will wait.

The analytical question is simpler. How much is the existing code costing per quarter in engineer time, incidents, and slow delivery? How much would it cost to replace? At what point does the replacement pay back its cost? If the break-even is within eighteen to twenty-four months, the rewrite deserves a real evaluation. If the break-even is three years out, the refactor is almost always the better call, because the rewrite estimate will be wrong by the time it is done.

Refactoring is not settling. It is precise surgery on the parts that are creating the most drag, while leaving the parts that work alone.

How to make the decision

The cost test

Before any rewrite conversation, put a number on the current maintenance cost. Hours per sprint spent on workarounds, bugs traced to this module in the last six months, features slowed because the module resists change. Translate to dollars. Then estimate the rewrite cost in engineer-weeks and translate that too.

If the monthly maintenance cost times eighteen months is greater than the rewrite cost, the rewrite is defensible. If not, the refactor is the right call.

The knowledge test

Every line of code that has been in production for more than a year contains implicit knowledge. Edge cases the team discovered through bugs. Business rules that were added quietly during an incident. Behaviors that customers depend on without knowing they do.

Before approving a rewrite, ask how much of that knowledge is documented anywhere other than the code. If the answer is "very little," the rewrite will rediscover those edge cases the hard way, in production, after the old code is gone.

The scope test

If the code that needs replacing is a module with a defined interface, a rewrite is more tractable. If the code is a cross-cutting concern that touches everything, a rewrite will expand until it consumes the entire codebase. The strangler fig is the right answer for cross-cutting concerns. The targeted rewrite is right for bounded modules.

What it costs

The full application rewrite rarely delivers on its original timeline. The average is two to three times the estimate. Plan accordingly or do not plan it.

What to look for before approving a refactor or rewrite

• A defined scope boundary with named modules in and out.
• Tests around the existing code before any structural change.
• An interface contract for the module that will stay stable during the change.
• A rollback path if the refactor introduces regressions.
• A team member who owns the work from start to finish without splitting focus.
• A defined done condition, not "when it feels clean."
• A communication plan for the rest of the team about what will and will not change.

Expert opinion

The refactor versus rewrite decision is almost always made emotionally and justified analytically afterward. Engineers who want to rewrite will find the numbers to support it. Engineers who want to refactor will find the numbers to support that. The discipline I hold to is: show me the maintenance cost first, then show me the replacement cost, and we will do the math together. The math almost always points to refactor.

>

Yashveer Singh, founder of Yashveer Labs

How this played out on a real project

A client came to me with a payment processing module that the team wanted to rewrite. The stated reason was that the code was "impossible to understand." The module had been in production for three years and processed several million dollars per year without a major incident.

We ran the two-day tech debt audit on the module. The actual cost of maintaining it was four hours per sprint, mostly because there were no tests and every change required manual verification. The rewrite estimate was six weeks. At the team's rate, that was about forty thousand dollars.

The math said: four hours per sprint at their blended rate was around two thousand dollars per month. The rewrite would pay back in twenty months. That was inside our eighteen-to-twenty-four month threshold, but only barely. We recommended a refactor instead: add tests first, then extract the pure logic, then improve the integration layer. Three weeks of work, not six. The module became maintainable without the risk of a full replacement.

The team initially pushed back. Two months after the refactor was done, they admitted it was the right call. The module still runs without incident. The code is now comprehensible. The rewrite would have been a distraction.

For the companion decision on how to structure the actual cleanup work, the refactor sprint post covers how to scope and run a focused sprint without derailing the delivery cadence.

Common mistakes

1. Starting the rewrite without testing the existing code first. The new code will miss behaviors that only existed in undocumented edge cases.
2. Letting scope creep expand the refactor into an accidental rewrite. Hold the module boundary.
3. Choosing to rewrite because the code is ugly, not because it is costly. Ugly code that works is not a business problem.
4. Running the refactor without a defined done condition. "Cleaner" is not a done condition. "Tests pass, module deploys independently, no cascading changes required" is.
5. Assigning the refactor to the most junior engineer because senior engineers are on feature work. Structural changes require structural judgment.
6. Not communicating the change to the rest of the team. Surprises in shared modules break other people's work.
7. Treating the refactor as invisible infrastructure work with no visibility in the sprint. It belongs on the board, with a ticket, and a done definition, the same as any feature.

A three-week refactor plan

1. Days one to three. Define the module boundary. Write down the interface contract. Add tests that freeze the current behavior, even if they are ugly.
2. Days four to eight. Refactor the internal structure. Do not change the interface. Run the tests after every meaningful change.
3. Days nine to twelve. Clean up the integration points. Update the tests to reflect the improved structure.
4. Days thirteen to fifteen. Deploy to staging, run the full test suite, deploy to production. Monitor for forty-eight hours.

For further reading on the related migration question, big bang vs gradual migration gives the structured decision map for when an architectural change is large enough to require a migration strategy rather than a sprint.