Extract dashboard cards into focused components (queues, upcoming plans, leadership status, recently visited, choropleth legend), compile the roadmap for outcome-oriented tracking, document the customer job and improve-app journey, and tighten roadmap skills with decision-quality gates.
178 lines
12 KiB
Markdown
178 lines
12 KiB
Markdown
# The Legacy Code Change Algorithm
|
|
|
|
The change algorithm is the spine of *Working Effectively with Legacy Code*: a fixed, repeatable procedure for changing code that has no tests. Improvisation is how the codebase got into this state; the algorithm replaces improvisation with five steps that are individually small, individually checkable, and always done in order:
|
|
|
|
1. Identify change points
|
|
2. Find test points
|
|
3. Break dependencies
|
|
4. Write tests
|
|
5. Make changes and refactor
|
|
|
|
## Table of Contents
|
|
|
|
- [The Dilemma](#the-dilemma)
|
|
- [Edit and Pray vs. Cover and Modify](#edit-and-pray-vs-cover-and-modify)
|
|
- [Two Kinds of Change, Never Mixed](#two-kinds-of-change-never-mixed)
|
|
- [The Five Steps on a Running Example](#the-five-steps-on-a-running-example)
|
|
- [The Safety Checklist](#the-safety-checklist)
|
|
- [Triage: "I Don't Have Much Time and I Have to Change It"](#triage-i-dont-have-much-time-and-i-have-to-change-it)
|
|
|
|
## The Dilemma
|
|
|
|
To change code safely, we need tests around it. To get tests around it, we usually have to change it — extract a parameter, loosen a type, route around a singleton. The legacy code dilemma is that the safety net requires the very kind of edit it is supposed to protect.
|
|
|
|
The resolution is asymmetry. The edits you make *before* tests exist belong to a restricted class: mechanical, conservative, signature-preserving moves chosen from a known catalog (see the dependency-breaking reference). The edits you make *after* tests exist can be ambitious. You earn the right to interesting changes by making boring ones first.
|
|
|
|
Two disciplines keep the pre-test edits safe:
|
|
|
|
- **Preserve signatures.** When moving or extracting code without tests, copy method signatures exactly — cut and paste, never retype. Every keystroke you don't make is a bug you can't introduce.
|
|
- **Lean on the compiler.** In typed languages, make a deliberate change (rename a variable, alter a constructor) and let the type errors enumerate every site that needs attention. The compiler becomes a crude but exhaustive impact analysis. In dynamic languages, lean on the import system and a fast grep instead — and trust them less.
|
|
|
|
## Edit and Pray vs. Cover and Modify
|
|
|
|
*Edit and pray* is the industry default: study the code, make the change very carefully, click around the app, deploy, hope. The praying isn't a joke — it is the actual verification strategy. Care is a real input to quality, but care without feedback is just slower gambling: nothing in the process *tells you* whether the change preserved behavior.
|
|
|
|
*Cover and modify* works with a net. Tests around the code act as a software vise: they clamp existing behavior in place so that when your change wiggles something you didn't intend, a test fails now, on your machine, pointing at the exact behavior that moved. The two styles also compound differently. Every edit-and-pray session leaves the code exactly as scary as it was. Every cover-and-modify session leaves a few tests behind, so the next change in that area starts cheaper.
|
|
|
|
## Two Kinds of Change, Never Mixed
|
|
|
|
There are four reasons to change software — add a feature, fix a bug, improve the design, optimize resource usage — and they collapse into two categories:
|
|
|
|
| Kind of change | What may change | What must be preserved |
|
|
|----------------|-----------------|------------------------|
|
|
| Behavior change (feature, bug fix) | One named, intended behavior | Every *other* behavior |
|
|
| Structure change (refactoring, optimization) | Code structure, resource usage | *All* functional behavior |
|
|
|
|
The discipline: never do both in the same step. A structure change starts green and ends green with no assertion edited. A behavior change updates or adds specific, named tests — and touches nothing else. When a mixed commit breaks something, you cannot tell whether the refactoring or the feature did it; when the steps are separate, the failing test plus the last commit is the whole diagnosis.
|
|
|
|
Practically this means alternating commits: `refactor: extract PriceCalculator (no behavior change)` then `feat: prorate first-cycle charges`. Reviewers can hold the first kind to "tests unchanged and green" and the second to "exactly these assertions changed."
|
|
|
|
## The Five Steps on a Running Example
|
|
|
|
The code below is typical legacy: useful, load-bearing, and hostile to tests.
|
|
|
|
```typescript
|
|
// billing/subscription-biller.ts
|
|
export class SubscriptionBiller {
|
|
charge(sub: Subscription): Receipt {
|
|
const gateway = new StripeGateway(process.env.STRIPE_KEY!);
|
|
let amount = sub.plan.priceCents;
|
|
if (sub.plan.interval === "year") {
|
|
amount = Math.round(amount * (1 - sub.plan.annualDiscount));
|
|
}
|
|
if (sub.coupon) {
|
|
amount -= this.couponValue(sub.coupon, amount);
|
|
}
|
|
amount += Math.round(amount * taxRateFor(sub.country));
|
|
const result = gateway.charge(sub.customerId, amount);
|
|
Mailer.getInstance().sendReceipt(sub.email, result);
|
|
AuditLog.write(`charged ${sub.id}: ${amount}`);
|
|
return new Receipt(sub.id, amount, result.transactionId);
|
|
}
|
|
}
|
|
```
|
|
|
|
The task: subscriptions started mid-cycle must be prorated for their first charge.
|
|
|
|
### Step 1: Identify change points
|
|
|
|
Where, exactly, will the edit live? Read until you can point at lines, not files. Here, proration affects the computation of `amount`, before tax — so the change point is the pricing block inside `charge()`. Identifying change points precisely matters because it determines *which behavior needs pinning*: everything that block currently does for existing subscriptions.
|
|
|
|
If you can't locate the change point — the feature seems to live "everywhere" — stop and use the comprehension tools from the untangling section (effect sketches, scratch refactoring) before going further.
|
|
|
|
### Step 2: Find test points
|
|
|
|
A test point is a place where you can write a test that detects the effects of your change. Change points and test points often differ: a private helper may be the change point while the public method that calls it is the only place its effects surface.
|
|
|
|
List the effects of `charge()`: the returned `Receipt`, the call to the gateway, the email, the audit line. The return value and the gateway call are the high-value sensing targets. `charge()` itself is the natural test point — *if* we can construct a `SubscriptionBiller` and substitute the gateway.
|
|
|
|
When many methods funnel through one place, that place is a **pinch point**: a narrowing in the effect graph where a few tests cover a lot of upstream behavior. Prefer pinch points when you must cover a wide area with a small test budget.
|
|
|
|
### Step 3: Break dependencies
|
|
|
|
Three blockers stand between `charge()` and a harness: the hard-wired `StripeGateway` (network), the `Mailer` singleton (SMTP), and the static `AuditLog` (filesystem). The least invasive fix for the first two is Parameterize Constructor with production defaults:
|
|
|
|
```typescript
|
|
export class SubscriptionBiller {
|
|
constructor(
|
|
private gateway: PaymentGateway = new StripeGateway(process.env.STRIPE_KEY!),
|
|
private mailer: ReceiptSender = Mailer.getInstance(),
|
|
) {}
|
|
|
|
charge(sub: Subscription): Receipt {
|
|
let amount = sub.plan.priceCents;
|
|
// ... pricing block unchanged ...
|
|
const result = this.gateway.charge(sub.customerId, amount);
|
|
this.mailer.sendReceipt(sub.email, result);
|
|
AuditLog.write(`charged ${sub.id}: ${amount}`);
|
|
return new Receipt(sub.id, amount, result.transactionId);
|
|
}
|
|
}
|
|
```
|
|
|
|
Notes on conservatism: production call sites compile untouched because of the defaults; `PaymentGateway` is an interface extracted only as wide as this class needs (one method, not Stripe's forty); `AuditLog` is left alone for now — if it writes synchronously to disk, a test-side temp directory may be cheaper than more surgery. One technique, one commit, build green, move on.
|
|
|
|
### Step 4: Write tests
|
|
|
|
Now pin current behavior with characterization tests (full procedure in the characterization reference). Cover the branches the change will touch — monthly, annual, coupon, a couple of tax countries:
|
|
|
|
```typescript
|
|
test("monthly DE subscription pins at plan price plus 19% tax", () => {
|
|
const gateway = new FakeGateway();
|
|
const biller = new SubscriptionBiller(gateway, new NullMailer());
|
|
const receipt = biller.charge(monthly({ priceCents: 3000, country: "DE" }));
|
|
expect(receipt.amountCents).toBe(3570); // observed, not designed
|
|
expect(gateway.charges).toEqual([{ customerId: "c_1", amountCents: 3570 }]);
|
|
});
|
|
```
|
|
|
|
The assertion records what the code *does*. If an observed value looks wrong, pin it anyway with a comment and a ticket — silently "fixing" it here would smuggle a behavior change into the safety-net step. Stop adding tests when every path through the pricing block is clamped.
|
|
|
|
### Step 5: Make changes and refactor
|
|
|
|
With the vise closed, work normally. Test-drive the new behavior: write the failing proration test, implement minimally, go green. Then — as a separate, structure-only step — clean up: the pricing block now has three tangled rules, so extract a `PriceCalculator` while the characterization tests stay green. Two commits, two kinds of change, each verifiable on its own.
|
|
|
|
## The Safety Checklist
|
|
|
|
**Before starting:**
|
|
- Working tree clean; you can revert any single step
|
|
- You can state in one sentence which behavior you intend to change — everything else must stay
|
|
- You know which kind of change each upcoming step is (behavior or structure)
|
|
|
|
**Before each dependency-breaking edit:**
|
|
- Is this the least invasive technique that unblocks a test?
|
|
- Are signatures preserved exactly — cut and paste, not retyped?
|
|
- Can the compiler or type-checker enumerate every affected site for you?
|
|
|
|
**After each dependency-breaking edit:**
|
|
- Build green; any existing tests green
|
|
- Production wiring provably unchanged (defaults still construct the real collaborators)
|
|
- Committed separately with a message that says "no behavior change"
|
|
|
|
**Before the behavior change:**
|
|
- Characterization tests pin every branch the change touches
|
|
- Each test would fail with a message that names the behavior that moved
|
|
|
|
**After the behavior change:**
|
|
- New behavior has its own intention-revealing tests
|
|
- Structure cleanups follow as separate green-to-green commits
|
|
- Any pinned bugs you decided to fix were flipped deliberately, assertion and fix in the same commit
|
|
|
|
## Triage: "I Don't Have Much Time and I Have to Change It"
|
|
|
|
The honest answer from the book: getting code under test pays back sooner than you fear — often the same afternoon, when your first regression is caught before commit. But sometimes the deadline is real and the class needs a day of dependency-breaking you do not have. Choose deliberately rather than guiltily:
|
|
|
|
| Situation | Move |
|
|
|-----------|------|
|
|
| Change is additive and plugs in at one point | Sprout Method: test-drive the new code, add one call line to the host |
|
|
| Host class won't instantiate at all | Sprout Class: new behavior in a new, fully tested class |
|
|
| Behavior surrounds the old code (logging, retry, notify) | Wrap Method or Wrap Class around the untouched original |
|
|
| A test point is reachable with minutes of work | Write the one pin test anyway — cheaper than the postmortem |
|
|
| No seams, no time, change forced inline | Pair on it, preserve signatures, single-goal editing — and file the debt ticket before you push |
|
|
|
|
Two rules make triage safe instead of corrosive:
|
|
|
|
1. **The second visit pays.** A spot that changes once can carry a sprout. The same spot changing again is the codebase telling you it is a hot path — get it under test on this visit, because you will be back.
|
|
2. **Sprout debt is visible debt.** Mark every untested host you sprouted into with a grep-able comment (`// SPROUTED: host untested — TICKET-512`) and an actual ticket. Unmarked shortcuts read as endorsed style to the next developer; marked ones read as a queue.
|
|
|
|
The algorithm looks slow on paper. In practice it is the fast path: the time sunk into dependency-breaking and pinning is bounded and front-loaded, while the time sunk into production regressions from edit-and-pray is unbounded and arrives at the worst moment. Teams that run the five steps stop being afraid of their own code — and fear, not the code, was the real bottleneck.
|