Capstone III: measure before and after

Pick the metric that the whole track was about: edits per logical change. Aesthetics (“cleaner”, “nicer”) are unfalsifiable and not what the codebase pays for. The honest measure is the one unit 00 named — change amplification: how many sites you must find and edit to make one conceptual change, and how many of those are easy to miss. Score the two target changes both ways.

// BEFORE — "add a new payment method (Klarna)"
//   touch PaymentForm.tsx      (new branch in a switch)
//   touch checkout.ts          (new branch in a switch)
//   touch refund.ts            (new branch in a switch)
//   touch reconcile.ts         (new branch — easy to forget → silent bug)
//   → 4 edits, 4 chances to miss one

// AFTER
//   add  KlarnaProvider implements PaymentProvider   (1 new file)
//   register it in the providers map                 (1 line)
//   → 1 localized add + 1 registration, 0 existing switches touched

The number that fell — from 4 scattered edits to one local addition — is the result. Everything else in this lesson explains why it fell.

Show coupling dropped, concretely — count the things that must change together. “Less coupled” is a claim; connascence and dependency direction are the evidence. Before, four modules were connascent of the payment-name strings: each switch had to know every payment type, so the four moved together. After, they depend on one PaymentProvider abstraction and know nothing about each other or about Klarna.

// BEFORE: every site is coupled to the full set of payment names
function fee(method: string) {
  switch (method) {            // checkout.ts knows: card, paypal, klarna…
    case "card":   return 0.029;
    case "paypal": return 0.034;
    // add klarna here AND in three other switches
  }
}

// AFTER: sites depend on the interface; providers are independent
interface PaymentProvider { fee(): number; charge(amt: number): Promise<Receipt>; }
const providers: Record<string, PaymentProvider> = { card, paypal, klarna };

The measurable drop: the number of files that must change together for “new payment method” went from 4 to 0 existing + 1 new. That is coupling, quantified — not a vibe.

Prove new test seams exist — by writing a test that was impossible before. A seam is a place you can substitute behaviour without editing the code under test. Before, fees lived inside a switch reached only by driving the whole checkout, so a fee test needed a fake cart, a fake user, and a network stub. After, KlarnaProvider.fee() is a pure unit you can assert directly — the seam is the interface.

// AFTER — a test that the BEFORE shape could not express in isolation
test("klarna fee is 1.9%", () => {
  expect(new KlarnaProvider().fee()).toBe(0.019);
});

// region-based tax got a seam too — inject the rate table, no globals
test("tax for EU region", () => {
  const tax = taxFor(100, "EU", { EU: 0.2, US: 0.0 });
  expect(tax).toBe(20);
});

The metric: testable units went from “fee logic reachable only through the full checkout flow” to “fee and tax assertable in two-line tests.” Unit 10’s safety net is what made the refactor safe; these seams are what the refactor produced.

Show cohesion rose — group the second target change and watch it land in one module. Cohesion is “things that change together live together.” The capstone’s second change — region-based tax — is the probe. Before, the 0.2 literal was smeared across pricing, invoicing, and reporting (low cohesion: one rule, many homes). After, the rule lives in tax.ts, so the region change is a single edit there and nothing else moves.

// AFTER — one home for the tax rule; region change is local to it
// tax.ts
export function taxFor(amount: number, region: Region, rates: RateTable): number {
  return amount * rates[region];          // ← region logic changes ONLY here
}

Measure it as before/after edits for “add region-based tax”: from 3 scattered sites (and a missed one becomes a bug) to 1. High cohesion is exactly what makes the expected change cheap — which is the only definition of “good” this track has used since unit 00.

Name the stopping rule, or the refactor never ends. The senior failure mode here is not under-refactoring — it is gold-plating: polishing past the point of payoff, adding flexibility for changes nobody asked for, chasing a perfect score on a module that is already good enough. A refactor is done when the expected changes are cheap and local — not when the code is flawless.

// STOP signal: re-score the two target changes.
//   "new payment method"  → 1 local add        ✓ cheap
//   "region-based tax"     → 1 local edit       ✓ cheap
// Both targets met → STOP. Do NOT now abstract currency, rounding,
// or a plugin system "while we're in here" — no change is asking for them.

The stopping criterion is concrete: state the changes you expect, refactor until those are single local edits, and stop. “Good enough for the changes we expect” beats “perfect,” because perfect spends today’s budget on changes that may never come — the exact mistake unit 00 warned against when it said changeability is a bet, not an absolute.