Legacy Code Modernization

"Legacy code" — the working definition from Michael Feathers — is code without tests. By that definition, most code is legacy. The looser definition, code written before the current team was responsible for it, captures the ongoing situation that most engineers spend most of their careers in. Modernizing legacy code is one of the most common engineering tasks and one of the most consistently mishandled.

This page is about the strategies that work, the rewrite-vs-refactor decision, and the patterns that make modernization survivable.

The honest assessment

Legacy code exists for reasons. The original engineers had constraints, deadlines, and information you do not have. The "ugly" patterns sometimes encode business knowledge that has since been forgotten. The "obvious" rewrite often misses what the legacy code was protecting against.

This is the first lesson: respect the code. Then change it.

The rewrite-vs-refactor decision

The single largest decision in legacy modernization. Common framings:

"Rewrite from scratch"

Throw out the old; build a new system that does the same thing. The case for: clean architecture, modern tools, no decade of accumulated patches.

The case against: rewrites take longer than estimated (always), rewrites lose accumulated business logic, rewrites introduce new bugs while old bugs are still being fixed in the legacy system.

The honest record: most "we'll rewrite it" projects fail. They miss deadlines, lose features the original had, take longer than the team has patience for.

"Refactor in place"

Keep the system running; improve it incrementally. The case for: continuous delivery, no big-bang risk, the team learns the system.

The case against: slow, painful, the structure may be too compromised to fix without rewriting.

When rewrite is correct

- The platform itself is end-of-life (no security updates, no community)

- The performance ceiling makes the requirements unattainable

- The system has accumulated debt to the point where any change is unsafe

- Business requirements have changed enough that the original architecture is wrong

When refactor is correct

- The system mostly works; specific parts need updating

- Continuous operation is required

- Risk of behavior changes is high

- The team can sustain incremental work over time

For most cases, refactor wins. Rewrites are seductive and rarely succeed.

The strategies for refactoring legacy

Characterization tests

Tests that pin down current behavior — including bugs — so you can refactor without changing it.

The pattern: write tests that capture what the code currently does. Do not try to test what it *should* do. Get coverage of the observable behavior. Now you have a safety net.

After characterization tests are in place, refactoring is dramatically safer. After refactoring, fix the bugs (if they are bugs) as separate, deliberate changes.

Strangler pattern

Build the new alongside the old; gradually move traffic. See [RefactoringStrategies](RefactoringStrategies) for detail. Works well when the system has clear boundaries.

Boundary tests

Test the boundary between systems, not internals. Two systems can produce the same external behavior with very different internals. Boundary tests let you replace internals freely.

Sprout method / sprout class

When you cannot easily modify a function, create a new function next to it. Call the new function from the old. The new code is testable; the old code is unchanged.

Over time, more code lives in the new functions than the old. Eventually the old wraps the new instead of the other way around.

Wrap method / wrap class

Wrap a hard-to-modify method with a new one that adds behavior. The original is preserved; new behavior is in the wrapper.

Edit the function from the inside out

For functions you cannot rewrite, you can sometimes refactor the inside while keeping the outside the same. Extract sub-functions, replace primitive types with proper types, add tests at the seams. The function eventually becomes a thin orchestrator over well-tested helpers.

The strategies for migration

When a real platform change is needed (Python 2 → 3, monolith → services, JavaScript → TypeScript):

Incremental conversion

Convert one module or one file at a time. Run both old and new in parallel. Each conversion is small and reversible.

Generated bridges

For language migrations, sometimes it's possible to auto-generate a bridge from old to new. The bridge is generated; the new code lives alongside.

Dual writes

For data migrations, write to both systems for a period. Verify they stay in sync. Eventually cut over reads.

Feature parity first, improvement later

The new system should match old-system behavior, including quirks. Once it has parity, improvements come as separate work. Mixing parity-restoration with improvement makes both harder.

The cultural side

Legacy modernization is as much about people as code:

The original engineers' knowledge

If they're still around, capture their knowledge. They know the constraints that aren't in the code: why this particular API call, why this specific error case, what the customer support implications are.

Avoiding the "we should rewrite this" trap

Engineers love to rewrite. New engineers especially. The company often does not benefit from the rewrite. Be explicit about the case before committing.

Documenting decisions

Every modernization decision should leave a record of why. Future engineers will need to understand the choices.

Patience

Legacy modernization is multi-year work. Set expectations accordingly; do not promise speed that requires a rewrite.

Specific patterns

"Why is this like this?"

Before changing legacy code, ask why it is the way it is. The answer often reveals constraints that should be preserved.

"What was the bug that produced this code?"

Comments and git blame can reveal that an "ugly" piece of code was the fix for a specific bug. Removing the ugliness without understanding the bug brings the bug back.

"What does this depend on that I'm not seeing?"

Legacy code often has hidden dependencies — environmental variables, specific OS, specific data shape. Find them before changing.

Read all the tests first

If tests exist, read them before reading the code. They often capture the intended behavior more clearly than the code.

Common failure patterns

- **Big-bang rewrites.** Almost always fail.

- **Refactoring without characterization tests.** Behavior changes silently.

- **"We'll add tests later."** Later doesn't come; legacy stays untested.

- **Treating legacy as inferior.** It often encodes knowledge the rewriting team doesn't have.

- **Modernizing for modernization's sake.** Without a specific goal, the work has no end.

- **No rollback plan.** Each migration step should be reversible.

- **Underestimating the original engineers.** They knew things you don't.

A reasonable workflow

For modernizing a specific legacy system:

1. **Read everything.** Code, tests, comments, design docs, commit history. Spend time understanding before deciding.

2. **Characterize.** Write tests that pin down current behavior.

3. **Identify the high-value targets.** Where is the modernization payoff highest?

4. **Plan in increments.** Each step should be 1–4 weeks of work, with a clear deliverable.

5. **Execute, verify, document.** Each step gets verified; each decision gets recorded.

6. **Don't fix bugs while refactoring.** Separate steps; separate commits.

7. **Communicate continuously.** The team and stakeholders need visibility.

The work is long; the steps are short.