Working With Legacy Code

Working Effectively with Legacy Code

A field manual for changing code that has no tests, distilled from Michael C. Feathers' Working Effectively with Legacy Code. Use it to get untestable classes into a harness, pin down current behavior with characterization tests, and make changes one safe, verifiable step at a time — without resorting to a rewrite.

Core Principle

Legacy code is simply code without tests. Not old code, not ugly code — untested code: without tests you cannot know whether a change preserves behavior, so every edit is a gamble. The craft is breaking dependencies just enough to get tests in place before changing anything — cover and modify, never edit and pray.

Scoring

Goal: 10/10. Rate changes to untested code 0-10 against the principles below. Report the current score and the specific steps needed to reach 10/10.

• 9-10: Change points covered by characterization tests before any edit; behavior changes and refactoring shipped as separate verified steps; dependencies broken with the least invasive technique
• 7-8: Tests at most change points, but occasional mixed refactor-plus-behavior commits or heavier dependency surgery than needed
• 5-6: Some characterization tests, yet key paths still changed on faith; sprouted code accumulating with no payback plan
• 3-4: Edit-and-pray with manual verification; tests written after the change, asserting whatever the new code happens to do
• 0-2: Untested edits straight into tangled code, refactoring and behavior change mixed in one commit, rewrite proposed instead of tests

Framework

1. The Legacy Code Dilemma and Change Algorithm

Core concept: The dilemma: to change code safely we need tests, but to get tests in place we have to change code. The way out is a fixed sequence — identify change points, find test points, break dependencies, write tests, then make changes and refactor — where the pre-test edits are conservative and mechanical, and the real change happens only inside the safety net.

Why it works: Edit-and-pray substitutes care for feedback, and care doesn't scale to code you don't fully understand. Cover-and-modify clamps existing behavior in a vise of tests, so any unintended change announces itself immediately on your machine instead of later in production.

Key insights:

• There are two reasons to change code — changing behavior (feature, bug fix) and improving structure (refactoring) — and mixing them in one step makes failures undiagnosable
• Test points are rarely the change points: effects propagate, so you often test where the change's effects surface, not where the edit happens
• Dependency-breaking edits made before tests exist must preserve signatures exactly and lean on the compiler to find every affected site
• Coverage grows along the paths you actually change — that beats any dedicated "testing project" that never gets funded
• "Programming is the art of doing one thing at a time": each step of the algorithm is separately verifiable

Applications:

See references/change-algorithm.md when running the five steps on a real change — the algorithm as a working procedure with change-point/test-point checklists and triage for "no time" situations.

2. Seams: Where to Pry Code Apart

Core concept: A seam is a place where you can alter behavior in your program without editing in that place. Every seam has an enabling point — where you decide which behavior runs. Getting legacy code under test is largely a hunt for seams: spots where a test can substitute a slow, global, or external dependency while the production source stays untouched.

Why it works: If you must edit code to test it, you risk changing the very behavior you are trying to pin down. Seams move the substitution to a distance — a subclass, an import, a build flag — so the code under test runs exactly as in production while the test controls its dependencies from the enabling point.

Key insights:

• Object seams are the default in OO code: every overridable call is a seam, and its enabling point is wherever the object is created or passed in
• Link and import seams swap implementations at build or load time — jest.mock and unittest.mock.patch are link seams in modern clothing
• Preprocessing seams (C/C++ macros) are the bluntest instrument; reach for them last
• new Database() inside a method body is a seam that never got built — constructors doing real work, globals, statics, and hard-wired I/O are where seams die
• A seam without a reachable enabling point is useless: if the test can't make the decision, keep hunting
• Dynamic languages make nearly every name lookup a seam — cheap, but patching internals couples tests to file layout

Applications:

See references/seams.md when hunting a seam in a specific stack — the seam catalog with code, enabling points, and seams in modern tooling (DI containers, jest.mock, pytest monkeypatch, clock and config seams).

3. Characterization Tests

Core concept: A characterization test documents what the code actually does right now — not what the spec, the comments, or anyone's memory says it should do. Write a probe you know will fail, let the failure message reveal the real behavior, then change the assertion to pin that behavior in place.

Why it works: In legacy systems the actual behavior is the de facto spec: callers, reports, and customers may depend on it, quirks included. Tests written from imagined requirements fail for reasons that tell you nothing, while characterization tests fail during refactoring precisely when — and where — you changed existing behavior.

Key insights:

• The recipe: call the code in a harness, assert something absurd (expect(total).toBe(-1)), read the failure, pin the observed value
• Sensing and separation are the two reasons to break dependencies: separation gets code into a harness, sensing lets assertions see what it computed
• For complex output (reports, generated files, large JSON) use a golden master: capture the full output once, diff against it forever
• Snapshot tests are golden masters — review the first snapshot like code and normalize volatile data, or you are pinning noise
• Found a bug while characterizing? Pin it with a comment and a ticket — downstream code may depend on the wrong behavior; fix it later as a deliberate, separate change
• Characterize the branches your change will touch, not the whole system — coverage follows change

Applications:

See references/characterization-tests.md when writing your first probe through to a pinned suite — golden masters, snapshot tests done right, and a worked before/after refactor.

4. Sprout and Wrap: Changing Without Tests First

Core concept: When you genuinely cannot get the area under test today, don't weave new logic into the untested mass. Sprout Method or Sprout Class: write the new behavior as fresh, fully tested code and call it from a single line in the legacy spot. Wrap Method or Wrap Class: rename the old code aside and add behavior before or after the call to it, decorator-style.

Why it works: New code in a fresh method or class can be test-driven even when its host can't be instantiated in a harness — testability no longer waits on getting the host into a harness. The untested host changes by exactly one call site, so the unverified blast radius is a single line instead of the whole method.

Key insights:

• Sprout Method when new logic plugs in at one point; Sprout Class when the host class won't even instantiate in a test harness
• Wrap Method suits behavior that surrounds the old code (logging, notification, metering) rather than mixes with it: rename pay() to rawPay(), recreate pay() as the wrapper
• Wrap Class is the Decorator pattern — use it when several call sites need the added behavior or the class is already bloated
• Be honest about the trade-off: the host stays untested; you have added good code to a bad neighborhood
• Track sprouts as debt and pay them back — cover the host the next time a change lands there
• Sprouting is a tactical move inside the change algorithm, not a permanent substitute for getting code under test

Applications: