Working with Legacy Code
In this pack:
sizing,
notation,
rule strictness.
Overview
Old code that no test covers answers the question "what does this do?"
with uncertainty. A change reaches a method nobody understands, a
constructor wants a database before the object exists, and a static call
leaves no place to put a stand-in. This skill makes the smallest safe
path through that code: pin what it does today, break one dependency at
a time with edits that move no logic, add the new rule as new code a
test can hold, and, when a whole part must go, move one capability at a
time behind the interface its callers already use. The old code changes
only where the task needs it.
When to use
- A class or routine must change and nothing tests the area the change
touches.
- A constructor does work a test cannot repeat, so a test cannot build
the class.
- Code reaches an outside system through a static call, and a test has
no place to put a stand-in.
- A new rule belongs in the middle of a long method that no test covers.
- A large old part must be replaced while its callers keep working.
- You are deciding what to leave alone in old code.
When not to use
Core rules
Rule. Before changing code that has no tests, record what it does
today with characterisation tests: feed it inputs from the area the
change will touch and check the output it gives now, even when that
output looks wrong. When an input shows a likely bug, write it
down and fix it in a separate change after the record is in place,
so the change you came for alters nothing else.
Rule. Until tests cover a class, change its dependencies only
through small, mechanical edits that leave every caller seeing the
same behaviour. Three such edits are: take a collaborator as a
constructor argument instead of building it inside; pull an
interface the class owns out of a concrete class it uses; put a
static call behind a method on an object the class receives. None of
them moves logic, and each is checked by reading the change,
building the program and running the tests that exist. Where every
caller cannot change in the same edit, keep the old construction
path in one named factory that passes the real collaborator: it
holds a break that already existed in one place, adds none, and goes
once every caller builds the class at the composition root, as
inverting dependencies
rule 3 asks.
Rule. Get a class under test through a seam: an interface the
class owns, with its collaborator passed in through the constructor,
so a test hands it a stand-in and never edits the class again.
This is the shape
inverting dependencies
rules 1 and 2 give new code; old code reaches it one dependency at a
time, starting with the one the change needs.
Default. Add new behaviour as new code, written test first, that
the old code calls: grow a new class that holds the logic, or wrap
the old class in a new one that answers the same interface and runs
the new step before or after it. The old code gains only the call
into the new code and the use of its answer, or nothing at all when
the wrapper takes its place; the rule itself lives in the new code.
The exception is old code that tests already cover where the change
lands: change it in place.
Judgement. Replace a large old part one piece at a time behind the
interface its callers already use, rather than rewriting it whole:
send one capability at a time to new code, keep the old part working
for the rest, and delete each old piece once nothing reaches it. A
rewrite in one go loses behaviour that nobody wrote down. What tips
the balance is whether old and new can run side by side: when the
new part speaks another model, a translating layer comes first, as
bounding contexts rule 4 places
one.
Default. Change only what the task needs, plus the seams and
tests that make that change safe, and leave the rest of the old code
alone until a change reaches it, as
recognising antipatterns
rule 5 leaves a stable part alone.
The exception is old code that the change history shows most coming
changes will pass through: pin it, then improve it in refactoring
steps of their own.
Pattern
Before, ReorderRun is old code with no tests. Its long run, left
out of the fence, sends orderItem for each item it finds below its
level, and orderItem sends supplier.order(item) once. The clinic now
needs a new rule: a controlled drug is reordered only with a
pharmacist's approval. Editing that rule into run would change code
no test covers.
Before:
class ReorderRun
- supplier: Supplier
+ new(supplier: Supplier)
+ orderItem(item: StockItem): void
supplier.order(item)
interface Supplier
+ order(item: StockItem): void
Before the edit, characterisation tests pin what orderItem and the
run around it do today (rule 1), and the fences leave those tests out.
After, Supplier is unchanged, and a new check guards the send.
After:
interface Supplier
+ order(item: StockItem): void
interface OrderApprovals
+ hasApproval(item: StockItem): Boolean
class ControlledItemCheck
- approvals: OrderApprovals
+ new(approvals: OrderApprovals)
+ mayOrder(item: StockItem): Boolean
if item.isControlled() then
return approvals.hasApproval(item)
else
return true
class ReorderRun
- supplier: Supplier
- check: ControlledItemCheck
+ new(supplier: Supplier, check: ControlledItemCheck)
+ orderItem(item: StockItem): void
if check.mayOrder(item) then
supplier.order(item)
return
ControlledItemCheck is new and written test first: the test builds it
with a stand-in for OrderApprovals and one controlled and one ordinary
item, sends mayOrder for both, and checks that the controlled item
follows the stand-in's answer while the ordinary item answers true
(rule 4). ReorderRun gains one field, one constructor parameter and
the one call whose answer guards the send, while the rule about
controlled items lives in ControlledItemCheck (rules 2 and 4); the one
place that builds ReorderRun at start-up now also builds the check.
StockItem.isControlled() is taken to answer whether the item is a
controlled drug, and Supplier.order is taken to send one order to the
supplier. true is the Boolean value. A controlled item without
approval is left for the run's other steps, which the fence leaves out.
The fences store nothing in the clinic's database. In each version,
orderItem sends at most one order for one call.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A change to code with no tests, and no characterisation test written
first.
- A constructor that reads a file or opens a connection, so no test can
build the class.
- A static call to an outside system from many places.
- New logic edited into the middle of a long untested method.
- A bug fixed in the same change that pins the behaviour.
- A rewrite planned in one go, with the old part switched off on one
day.
Common mistakes
- Writing tests for what the code should do before pinning what it does.
- Cleaning up untested code beyond what the change needs.
- Moving logic while breaking a dependency, before any test covers it.
- Keeping the named factory after every caller can pass the
collaborator.
- Replacing the old part's interface while moving its pieces, so
callers change twice.
Related skills
Further reading
- Characterisation tests
- Breaking dependencies
- Replacing an old part piece by piece
1---2name: oo-working-with-legacy-code3description: Use when changing software that has no tests, when an old class must change before it can be tested, or replacing an old system piece by piece.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-working-with-legacy-code7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Working with Legacy Code1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920Old code that no test covers answers the question "what does this do?"21with uncertainty. A change reaches a method nobody understands, a22constructor wants a database before the object exists, and a static call23leaves no place to put a stand-in. This skill makes the smallest safe24path through that code: pin what it does today, break one dependency at25a time with edits that move no logic, add the new rule as new code a26test can hold, and, when a whole part must go, move one capability at a27time behind the interface its callers already use. The old code changes28only where the task needs it.2930## When to use3132- A class or routine must change and nothing tests the area the change33 touches.34- A constructor does work a test cannot repeat, so a test cannot build35 the class.36- Code reaches an outside system through a static call, and a test has37 no place to put a stand-in.38- A new rule belongs in the middle of a long method that no test covers.39- A large old part must be replaced while its callers keep working.40- You are deciding what to leave alone in old code.4142## When not to use4344- Tests already cover the code and would catch a change in behaviour:45 that is46 [refactoring toward object design](../oo-refactoring-toward-object-design/SKILL.md).47- The code is new and its design is still open: that is48 [designing for testability](../oo-designing-for-testability/SKILL.md).49- The question is which antipattern in the old code to treat first:50 that is51 [recognising antipatterns](../oo-recognising-antipatterns/SKILL.md).52- The old part is a separate system another team owns, and the question53 is how two models talk: that is54 [bounding contexts](../oo-bounding-contexts/SKILL.md).5556## Core rules57581. Rule. **Before changing code that has no tests, record what it does59 today with characterisation tests: feed it inputs from the area the60 change will touch and check the output it gives now, even when that61 output looks wrong.** When an input shows a likely bug, write it62 down and fix it in a separate change after the record is in place,63 so the change you came for alters nothing else.64652. Rule. **Until tests cover a class, change its dependencies only66 through small, mechanical edits that leave every caller seeing the67 same behaviour.** Three such edits are: take a collaborator as a68 constructor argument instead of building it inside; pull an69 interface the class owns out of a concrete class it uses; put a70 static call behind a method on an object the class receives. None of71 them moves logic, and each is checked by reading the change,72 building the program and running the tests that exist. Where every73 caller cannot change in the same edit, keep the old construction74 path in one named factory that passes the real collaborator: it75 holds a break that already existed in one place, adds none, and goes76 once every caller builds the class at the composition root, as77 [inverting dependencies](../oo-inverting-dependencies/SKILL.md)78 rule 3 asks.79803. Rule. **Get a class under test through a seam: an interface the81 class owns, with its collaborator passed in through the constructor,82 so a test hands it a stand-in and never edits the class again.**83 This is the shape84 [inverting dependencies](../oo-inverting-dependencies/SKILL.md)85 rules 1 and 2 give new code; old code reaches it one dependency at a86 time, starting with the one the change needs.87884. Default. **Add new behaviour as new code, written test first, that89 the old code calls: grow a new class that holds the logic, or wrap90 the old class in a new one that answers the same interface and runs91 the new step before or after it.** The old code gains only the call92 into the new code and the use of its answer, or nothing at all when93 the wrapper takes its place; the rule itself lives in the new code.9495 The exception is old code that tests already cover where the change96 lands: change it in place.97985. Judgement. **Replace a large old part one piece at a time behind the99 interface its callers already use, rather than rewriting it whole:100 send one capability at a time to new code, keep the old part working101 for the rest, and delete each old piece once nothing reaches it.** A102 rewrite in one go loses behaviour that nobody wrote down. What tips103 the balance is whether old and new can run side by side: when the104 new part speaks another model, a translating layer comes first, as105 [bounding contexts](../oo-bounding-contexts/SKILL.md) rule 4 places106 one.1071086. Default. **Change only what the task needs, plus the seams and109 tests that make that change safe, and leave the rest of the old code110 alone until a change reaches it, as111 [recognising antipatterns](../oo-recognising-antipatterns/SKILL.md)112 rule 5 leaves a stable part alone.**113114 The exception is old code that the change history shows most coming115 changes will pass through: pin it, then improve it in refactoring116 steps of their own.117118## Pattern119120Before, `ReorderRun` is old code with no tests. Its long `run`, left121out of the fence, sends `orderItem` for each item it finds below its122level, and `orderItem` sends `supplier.order(item)` once. The clinic now123needs a new rule: a controlled drug is reordered only with a124pharmacist's approval. Editing that rule into `run` would change code125no test covers.126127Before:128129```text130class ReorderRun131 - supplier: Supplier132 + new(supplier: Supplier)133 + orderItem(item: StockItem): void134 supplier.order(item)135136interface Supplier137 + order(item: StockItem): void138```139140Before the edit, characterisation tests pin what `orderItem` and the141run around it do today (rule 1), and the fences leave those tests out.142After, `Supplier` is unchanged, and a new check guards the send.143144After:145146```text147interface Supplier148 + order(item: StockItem): void149150interface OrderApprovals151 + hasApproval(item: StockItem): Boolean152153class ControlledItemCheck154 - approvals: OrderApprovals155 + new(approvals: OrderApprovals)156 + mayOrder(item: StockItem): Boolean157 if item.isControlled() then158 return approvals.hasApproval(item)159 else160 return true161162class ReorderRun163 - supplier: Supplier164 - check: ControlledItemCheck165 + new(supplier: Supplier, check: ControlledItemCheck)166 + orderItem(item: StockItem): void167 if check.mayOrder(item) then168 supplier.order(item)169 return170```171172`ControlledItemCheck` is new and written test first: the test builds it173with a stand-in for `OrderApprovals` and one controlled and one ordinary174item, sends `mayOrder` for both, and checks that the controlled item175follows the stand-in's answer while the ordinary item answers `true`176(rule 4). `ReorderRun` gains one field, one constructor parameter and177the one call whose answer guards the send, while the rule about178controlled items lives in `ControlledItemCheck` (rules 2 and 4); the one179place that builds `ReorderRun` at start-up now also builds the check.180`StockItem.isControlled()` is taken to answer whether the item is a181controlled drug, and `Supplier.order` is taken to send one order to the182supplier. `true` is the Boolean value. A controlled item without183approval is left for the run's other steps, which the fence leaves out.184The fences store nothing in the clinic's database. In each version,185`orderItem` sends at most one order for one call.186187## Red flags188189Places to look, not verdicts. A red flag becomes a finding only with190evidence: a measurement, a reproducible bug, or a failing test.191192- A change to code with no tests, and no characterisation test written193 first.194- A constructor that reads a file or opens a connection, so no test can195 build the class.196- A static call to an outside system from many places.197- New logic edited into the middle of a long untested method.198- A bug fixed in the same change that pins the behaviour.199- A rewrite planned in one go, with the old part switched off on one200 day.201202## Common mistakes203204- Writing tests for what the code should do before pinning what it does.205- Cleaning up untested code beyond what the change needs.206- Moving logic while breaking a dependency, before any test covers it.207- Keeping the named factory after every caller can pass the208 collaborator.209- Replacing the old part's interface while moving its pieces, so210 callers change twice.211212## Related skills213214- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule215 labels.216- [oo-testing-object-oriented-code](../oo-testing-object-oriented-code/SKILL.md)217 writes and names the tests that replace the pin once the rule is218 clear.219- [oo-designing-for-testability](../oo-designing-for-testability/SKILL.md)220 shapes a seam in new code so a test can choose its collaborators.221- [oo-refactoring-toward-object-design](../oo-refactoring-toward-object-design/SKILL.md)222 takes the tidy-up steps once tests cover the code a change touches.223- [oo-inverting-dependencies](../oo-inverting-dependencies/SKILL.md)224 puts a port beside the domain and builds the graph at the composition225 root, which rules 2 and 3 rely on.226- [oo-bounding-contexts](../oo-bounding-contexts/SKILL.md) places a227 translating layer where two models meet, which rule 5 uses.228- [oo-recognising-antipatterns](../oo-recognising-antipatterns/SKILL.md)229 finds the old part that changes most, which rule 6 uses to order the230 work.231232## Further reading233234- [Characterisation tests](references/characterisation-tests.md)235- [Breaking dependencies](references/breaking-dependencies.md)236- [Replacing an old part piece by piece](references/replacing-an-old-part-piece-by-piece.md)