Dead code & speculative generality

Dead code is code that cannot affect the program’s output — and it still costs you. It comes in a few recurring shapes:

// 1. unused parameter — every caller passes something the body ignores
function priceOf(item: Item, _currency: string): number {
  return item.cents / 100; // currency is never read
}

// 2. unreachable branch — the guard above already returns
function classify(n: number): string {
  if (n >= 0) return "non-negative";
  if (n < 0) return "negative";
  return "impossible"; // dead: every number is one or the other
}

// 3. commented-out block — a fossil nobody dares delete
// function oldExport() { ...40 lines... }

// 4. never-called function — exported, imported nowhere
export function legacyMigrate() { /* ... */ }

The damage is not that it runs wrong — it does not run at all. The damage is that a reader cannot know it’s dead without proving it, so every one of these forces a small investigation: “is _currency used somewhere I can’t see? does anything still call legacyMigrate?” That tax is paid on every read, by every future maintainer, forever.

Speculative generality is flexibility built for a requirement that never came. Dead code is at least honest — it once did something. Speculative generality never did. It is the abstraction, hook, or parameter added “in case we need it”:

// one subclass, ever — the abstraction buys nothing
abstract class Exporter {
  abstract format(rows: Row[]): string;
}
class CsvExporter extends Exporter { format(rows: Row[]) { /* ... */ return ""; } }
// no other Exporter exists, none is planned

// a strategy parameter only ever called one way
function render(view: View, strategy: "default" | "fast" = "default") {
  // 'fast' branch was never written; callers never pass it
}

// a config flag wired through three layers, always the same value
const FEATURE_NEW_PIPELINE = false; // shipped false, never flipped

Each of these adds an indirection, a branch, or a type union you must hold in your head to read the code — and none of it does anything. You pay the full comprehension and maintenance cost of flexibility while getting zero flexibility back, because the variation it was built for does not exist.

Unused flexibility is not an asset on the balance sheet — it is a liability. This is the senior reframe. “We might need it later” treats an abstraction as a saved investment. It is the opposite: every extension point is more surface to read, more code paths to test, more constraints on the next refactor (you can’t simplify Exporter away without checking the abstract contract), and more onboarding load. An empty strategy branch is a lie the type system tells — it claims a behaviour that does not exist.

The asset is delivered behaviour you use. Flexibility you don’t use is undelivered cost. YAGNI — You Aren’t Gonna Need It — is the economic statement of this: building for a speculative future loses on average, because most speculated futures never arrive, and the ones that do rarely match the shape you guessed. You pay the carrying cost now, with interest, for an option you usually never exercise.

The cure is delete — and version control is what makes it fearless. The reason engineers hoard dead code is the fear “what if we need it again?” Git answers that completely: deleted code is not gone, it is one git log / git show away, with its full history and the commit message explaining why it existed. Commented-out blocks are worse than deletion — they rot (the surrounding API drifts, so the fossil no longer even compiles), they pollute search results, and they carry no history. Delete them; the real version is in the log.

// before — the fossil and the flag, in the reader's way
function priceOf(item: Item, _currency: string): number { return item.cents / 100; }
// function oldPriceOf(item) { ...40 dead lines... }

// after — what the code actually does, and nothing else
function priceOf(item: Item): number {
  return item.cents / 100;
}

So delete fearlessly: unused params, unreachable branches, never-called exports, single-implementation abstractions, dead flags. The bet YAGNI makes is that re-adding the abstraction when you actually have the second case is cheaper than carrying it speculatively until then — and that bet is almost always right, because the second case tells you the real shape the abstraction needs.

The failure mode: deleting a genuinely-needed extension point because it has only one caller today. “One subclass” and “one caller” are the symptoms of speculative generality — but they are also what a correct, deliberate seam looks like the moment before its second use lands. The single-caller PaymentProvider interface with only StripeProvider behind it may be over-engineering — or it may be the boundary your team agreed on last sprint because the PayPal integration starts Monday and the seam is load-bearing for a contract test or a plugin API.

Before you delete, confirm it is speculative, not early:

• Is there a concrete, committed plan or an existing consumer (a test double, a public API boundary, a second implementation in flight)? Then it is early infrastructure — keep it.
• Is it “we might want to swap this someday” with no second case in sight, no test exercising the seam, and no caller using the abstraction? Then it is speculative — delete it and re-add when the real case appears.

The senior move is not “never abstract” and not “delete everything with one caller.” It is distinguishing flexibility you are paying for and not using from a seam you are about to use, and being honest about which one you’re looking at.