teqo/.agents/skills/working-with-legacy-code/references/change-algorithm.md
Francisco Ignácio Fontoura Solla b75daab498 Refactor campaign dashboard UX and add product discovery artifacts.
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.
2026-07-19 21:56:01 -03:00

12 KiB

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

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.

// 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:

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:

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.