← All articlesInfra and cloud

Rewrite vs refactor: what to do with a codebase nobody wants

A full rewrite always looks tempting. It is rarely justified. Here is how to decide, and how to replace old code without stopping delivery.

Julien Mauclair · ~5 min · intermediate
StackGitProxyTests

In most cases, do not rewrite everything: replace the code piece by piece, one feature at a time, while the old system keeps running. A full rewrite is only justified in a few specific cases, listed below.

Martin Fowler sums up his teams' experience: the "rebuild the same thing, but better" plan usually goes down in flames, because a serious system takes a long time to replace and its real behaviour is poorly understood (Martin Fowler, Strangler Fig).

01Why full rewrites fail so often

A codebase nobody wants is almost always a codebase that works. Its overlong functions hold fixes accumulated from bugs found in production. Joel Spolsky made the point back in 2000 about Netscape, which went almost three years without a major release during its rewrite: throwing the code away means throwing away all those fixes and handing years to your competitors (Joel Spolsky, Things You Should Never Do).

Three mechanisms show up every time:

·the product freezes: users wait for new features while the team recodes what already exists;
·implicit business rules get lost, because nobody wrote them down anywhere except in the code;
·some of the old behaviour was no longer needed, but it gets rebuilt anyway because nobody knows which part.

There is a human bias too. Reading code is harder than writing it, so other people's code always looks worse than it is. In an r/cto thread, a former CTO of two startups describes treating every architecture decision as permanent, even though much of it was replaced a few months later (r/cto discussion). Code is not a monument: it is a temporary state you keep evolving.

02The criteria to decide

Before deciding, answer these questions. Each answer pushes one way.

QuestionWhat it tells you
Is the system small and well understood?Rewriting may be simpler than migrating
Is the technology unmaintained or no longer deployable?A serious case for rewriting, at least that layer
Can requests go through a proxy or facade?Gradual migration is possible
Can you change the old system's source code or database?Gradual migration is possible
Must the product keep shipping during the work?Gradual migration, almost mandatory
Are business rules documented nowhere?Do not rewrite without characterization tests
Does the pain come from a handful of files?Targeted refactoring, not a rewrite

The Azure documentation for the pattern says the same from another angle: gradual migration does not fit when requests cannot be intercepted, when there is no integration point you can change, or when the system is small enough to replace in one go (Microsoft, Strangler Fig pattern). Outside those cases, piece-by-piece replacement wins.

Find where the code really hurts

The feeling that "everything must go" can be checked. The areas to tackle first are the ones that change often: that is where debt costs you, on every release. This Git command lists the most modified files over the last twelve months:

hotspots.shBASHCopy
git log --format=format: --name-only --since=12.month \
| grep -v '^$' \
| sort | uniq -c | sort -nr | head -20

Cross that list with the files behind most bugs and incidents. If a handful of files stand out, the diagnosis is clear: targeted refactoring is enough and a rewrite would be overkill. If the pain is everywhere and the technology itself is blocking, the rewrite question becomes legitimate. This triage is also at the heart of a technical due diligence before a raise or an acquisition.

03Migrate piece by piece with a strangler fig

The principle, described by Fowler and taken up by Microsoft: a facade placed in front of the old system receives every request. At first it sends almost all of them to the old code. At each step, one feature is rebuilt in the new system and the facade routes the matching traffic to it. When nothing depends on the old system anymore, you switch it off, then remove the facade (Microsoft, Strangler Fig pattern).

The order that keeps risk low:

1. Agree on the outcomes: ship faster, reduce incidents, leave a dead technology. Without a shared goal, the migration drifts. 2. Write characterization tests on the critical paths: they freeze current behaviour, bugs included, so any difference shows up. 3. Put the facade in place: a reverse proxy, an API gateway or routing inside the app. 4. Pick the first slice where value is high and coupling is low, ideally a new feature. 5. Shift traffic gradually, with a rollback available at each step. A boring deployment makes those switches routine. 6. Decommission as you go, so you do not maintain two systems forever.

Careful

Transitional code (facade, adapters, dual writes) is meant to disappear. It looks like waste, but it is the price of a migration without downtime. Make sure it does not become a single point of failure.

The trickiest part is usually the database shared by the old and new systems. Decide early who writes what, and add an adaptation layer so the new code does not inherit the old one's conventions.

Finally, change how the team works as well. Fowler insists that without organisational change, the new system will end up in the same state as the old one. This is often where a fractional CTO adds the most: setting the criteria, ordering the slices and holding the course over several months.

04FAQ

How long does a gradual migration take?

Longer than a rewrite on paper, but it delivers value from the first slice and can stop at any point without losing everything. The duration depends on the number of slices and on how coupled the database is.

When should you rewrite everything anyway?

When the system is small and well understood, when the technology can no longer be maintained or deployed, or when requests cannot be intercepted at all. Even then, write characterization tests first so nothing gets lost along the way.

Isn't refactoring just kicking the can down the road?

Not if it targets the files that change the most and follows a measurable goal. Kicking the can is fixing things at random with no priority. The hotspot command above exists precisely to choose.

In short

A big-bang rewrite bets the product on a project you cannot see the end of. Replace it piece by piece, measure each step, and keep the full rewrite for the rare cases where nothing else holds.

Talk about your project ↗
Julien MauclairJulien Mauclair is the co-founder and CTO of Klickbee, where he builds the agency’s websites, tracking and AI automations, and develops Klickbee Tracking. He also runs Stralya, which designs and runs AWS infrastructure for scale-ups. Before that, he built the entire AWS infrastructure of an e-commerce business, since sold.

Read next