Every successful company has legacy code: the billing module nobody fully understands, the 3,000-line controller, the cron job written by someone who left four years ago. It still makes money, which is exactly why it is scary to touch. The temptation is either to leave it alone forever or to start a big rewrite. Both usually fail. The safer path is to refactor legacy code in small, reversible steps, with production safety built into every one of them.
Why Big Rewrites Usually Fail
A full rewrite looks clean on a whiteboard. In practice, the old system contains years of edge cases, bug fixes, and business rules that nobody documented. The rewrite takes longer than planned, the business keeps changing the old system in the meantime, and on launch day the new version is missing behavior users relied on. Incremental refactoring keeps the system running and delivering value while it improves.
Step 1: Understand Before You Change
Start by reading, not editing. Trace the main flows, find where the code is called from, and look at logs and metrics to see which paths are actually used in production. Check version control history for the files that change and break most often; those hotspots are where refactoring pays off first. If you need a refresher on spotting structural problems, see 10 signs your code structure is becoming unmaintainable.
Step 2: Lock Current Behavior With Characterization Tests
Legacy code often has no tests, and you may not even know what "correct" means. Characterization tests solve this: they record what the code does today, right or wrong, so you notice if a refactor changes it.
- Call the code with realistic inputs and assert the current outputs.
- Use real production examples where possible, with personal data anonymized.
- For large outputs such as reports or invoices, use snapshot or approval tests.
- If you find a bug, write it down and fix it in a separate change, not during the refactor.
Step 3: Make Small, Behavior-Preserving Changes
Refactoring means changing structure without changing behavior. Work in tiny steps: rename a confusing variable, extract a function, remove dead code, introduce a parameter object. Each step should be easy to review and safe to deploy on its own. Keep refactoring commits separate from feature commits so reviewers and future debuggers can tell them apart. The goal is the same one described in why your code works but is still bad code: readable, changeable, testable code.
Step 4: Create Seams to Break Dependencies
Legacy code is hard to test because it is tangled with the database, global state, the current time, or external APIs. A seam is a place where you can swap behavior without editing the code around it. Wrap the external call behind an interface, pass dependencies in instead of creating them inside, and inject a clock instead of calling the current time directly. Each seam makes the next change safer.
Step 5: Use the Strangler Fig Pattern for Bigger Changes
When a whole module needs replacing, build the new version alongside the old one and route traffic to it gradually. Put a router, proxy, or feature flag in front, send a small share of requests to the new code, compare results, and increase the share as confidence grows. When the new path handles everything, delete the old one. At any point you can roll back by flipping the flag, without a deploy.
Step 6: Compare Old and New in Production
For critical logic such as pricing, tax, or permissions, run both versions side by side: the old code still serves the response, while the new code runs in the background and its result is compared and logged. This "shadow" or "parallel run" approach exposes differences on real data before any user is affected. Fix the differences, then switch over.
Step 7: Deploy Safely and Watch Closely
- Deploy small changes often instead of one big release.
- Use feature flags and canary releases to limit the blast radius.
- Monitor error rates, latency, and key business metrics like orders or payments after each step.
- Prepare a rollback plan before deploying, not after something breaks.
- Be careful with database changes: use expand-and-contract migrations, adding new columns first and removing old ones only when nothing uses them.
If something does go wrong, a calm, systematic investigation helps; our guide on how to find the root cause of a production bug walks through it.
Step 8: Make Refactoring Part of Normal Work
Legacy code improves fastest when refactoring is continuous, not a special project that gets cancelled. Follow the boy-scout rule, improving the code you touch for each feature. Reserve some capacity each sprint for hotspots, and explain the business value in terms managers care about: fewer incidents, faster features, easier onboarding.
A Safe Refactoring Checklist
- Do you understand how the code is used in production?
- Are characterization tests in place for the behavior you will touch?
- Is the change small and behavior-preserving?
- Is it separate from feature or bug-fix changes?
- Can you roll it back quickly with a flag or a revert?
- Are you monitoring the right metrics after deploying?
Conclusion
You don't have to choose between living with legacy code forever and a risky rewrite. Understand the system, lock in behavior with tests, change it in small steps, use seams and the strangler fig pattern for bigger moves, and deploy with flags and monitoring. Done this way, legacy code gets better every week while production stays stable.