The maintainability triad

Maintainability is not one property — it is three measurable, separable ones. “Cheap to change” bundles three distinct costs, and you should be able to score code on each independently:

• Readability — the cost to understand what this code does and why, from a cold start. Measured in how long a competent reader takes to be sure.
• Changeability — the cost to safely modify it: how many places you must touch, how big the blast radius is, how confident you can be you didn’t break a caller.
• Testability — the cost to verify a unit in isolation: can you exercise this logic without standing up a database, faking the clock, or running the whole app?

These are the axes a senior actually grades on. “Good code” means high marks on all three; “bad code” usually fails one specific axis, and naming which one is the whole point.

They are correlated but separable — and the gaps between them are where bugs hide. The properties tend to move together: well-named, cohesive code is usually easy to read, change, and test. That correlation is real, which is why beginners treat “good code” as one thing. But they come apart often enough that conflating them is a senior-level mistake:

// Readable. Obvious intent. Untestable.
function isTrialExpired(user: User): boolean {
  const elapsedDays = (Date.now() - user.signupAt) / 86_400_000;
  return elapsedDays > 14;
}

You can read this in five seconds — readability is high. But you cannot write a deterministic unit test for it: the Date.now() makes the result depend on when the test runs. To test “expired” vs “not expired” you’d have to mock global time, fake the system clock, or sleep. The function is readable and untestable at the same time. The two properties just diverged.

The usual culprit for low testability is a hidden dependency: time, IO, randomness, or global state reached for directly. Date.now(), Math.random(), process.env, fetch, fs.readFileSync, a module-level singleton — each is a dependency the function grabs from the ambient environment instead of receiving. It reads fine because the dependency is invisible in the signature. That invisibility is exactly what kills testability: a test can only control what it can pass in, and you can’t pass in something the function reaches for behind your back.

// Readable, and just as untestable: pulls config from the ambient env.
function buildApiUrl(path: string): string {
  const base = process.env.API_BASE ?? "https://prod.example.com";
  return `${base}${path}`;
}

To test the staging branch you’d mutate process.env (global, leaks between tests) and remember to restore it. The signature (path: string) => string lies: the function actually depends on path and the environment. Untestability is usually a signature that doesn’t tell the truth about its inputs.

Inject the hidden dependency and testability rises with readability untouched. Make the dependency a parameter — a now value, a clock, a config object. The logic doesn’t change; the signature stops lying; the test gets a seam to pass values through.

// Same logic, same clarity — now deterministically testable.
function isTrialExpired(user: User, now: number): boolean {
  const elapsedDays = (now - user.signupAt) / 86_400_000;
  return elapsedDays > 14;
}

// Test controls time. No mocking, no sleeping, no global state.
isTrialExpired({ signupAt: 0 }, 13 * 86_400_000); // false
isTrialExpired({ signupAt: 0 }, 20 * 86_400_000); // true

Read it again: it is exactly as easy to understand as before. We spent no readability and bought full testability. That is the ideal move — and it shows the properties are separable in the good direction too: you can raise one without paying with another. The cost is pushed up to the caller (it must supply now: Date.now() once at the edge), which is precisely where the real, untestable clock belongs.

The failure mode: chasing one property can wreck the other two. Because the axes are separable, you can over-optimise one and pay on the others. The classic case is testability bought with mocking and indirection:

// "Testable" — but readability and changeability are now wrecked.
class TrialChecker {
  constructor(
    private clock: IClock,
    private config: IConfig,
    private logger: ILogger,
    private featureFlags: IFeatureFlags,
  ) {}
  isExpired(user: User): boolean {
    this.logger.debug("checking");
    const limit = this.config.get("trialDays");
    if (!this.featureFlags.isOn("trials")) return false;
    return (this.clock.now() - user.signupAt) / 86_400_000 > limit;
  }
}

Each interface exists “to be mockable,” but now: reading the rule means chasing four abstractions; the unit test needs four mocks just to assert a date comparison; and changing the rule means touching the class, its interfaces, and every test’s mock setup. Testability went up by a hair and readability + changeability collapsed. The senior instinct: a plain now: number parameter gave you the same testability for free. Indirection is a cost, not a default — add a seam only where a real, hard-to-control dependency lives.