06-22-2026, 12:45 PM
Legacy code refactoring is one of the riskiest things you can do because the original author's reasoning is often lost, tests are sparse, and the blast radius of changes is unclear. Here's what works.
Step 1: Understand before touching
Read it. Run it. Add logging to understand the execution path. Don't start changing things until you understand what the code does, even if not why.
Step 2: Add tests before refactoring
If there are no tests, write characterisation tests first. These aren't tests of what the code should do - they document what it currently does, including any bugs. Now you have a safety net.
Step 3: Refactor in small steps
The goal is to keep the code working at every step. Extract a function. Rename a variable. Simplify a condition. Run tests after each change. A PR that changes logic AND refactors structure simultaneously is impossible to review and risky to merge.
The Strangler Fig pattern
For large systems: build new behaviour alongside old code, gradually redirect traffic to the new path, then delete the old code once the new is proven. Never do a big bang rewrite.
Common traps:
When to not refactor:
If the code works, is rarely touched, and has no tests - leave it alone. The cost of adding tests and refactoring isn't always worth it for stable code that doesn't change.
Step 1: Understand before touching
Read it. Run it. Add logging to understand the execution path. Don't start changing things until you understand what the code does, even if not why.
Step 2: Add tests before refactoring
If there are no tests, write characterisation tests first. These aren't tests of what the code should do - they document what it currently does, including any bugs. Now you have a safety net.
Step 3: Refactor in small steps
The goal is to keep the code working at every step. Extract a function. Rename a variable. Simplify a condition. Run tests after each change. A PR that changes logic AND refactors structure simultaneously is impossible to review and risky to merge.
The Strangler Fig pattern
For large systems: build new behaviour alongside old code, gradually redirect traffic to the new path, then delete the old code once the new is proven. Never do a big bang rewrite.
Common traps:
- Refactoring and fixing bugs simultaneously - you won't know which change introduced a regression
- Gold-plating - refactoring is not the time to add new features or redesign the architecture
- Scope creep - "while I'm here" changes multiply risk. Separate PRs for separate concerns.
- Not communicating to the team - if someone else is working in the same area, coordinate
When to not refactor:
If the code works, is rarely touched, and has no tests - leave it alone. The cost of adding tests and refactoring isn't always worth it for stable code that doesn't change.