Lesson 0030 · Master Designer · Module 1

Generality vs Specificity

A general module is a bet on the future; a specific module is a fact about today. Ousterhout's law: generality is earned when it makes the specific case simpler — not when it adds cases.

Reading ≈ 8 minPractice ≈ 40 min

Mission tie-in: the last Complexity Trade-Off — and the one that decides how much machinery every module carries.

Knowledge: generality that pays vs generality that costs

Two kinds of generality:

1. Earned generality — the module solves today's case through a shape that naturally covers tomorrow's. It makes the current code simpler because the general interface is cleaner than the specific one.
2. Speculative generality — parameters, hooks, and abstractions for cases that don't exist. It taxes every read of the current code to pay for futures that may never arrive.

# speculative: a "pipeline" framework for one transformation
class Transformer:
    def __init__(self, steps: list[Step], concurrency: int = 1,
                 retry: RetryPolicy | None = None, metrics: Metrics | None = None):
        ...

Transformer(steps=[normalize], concurrency=1, retry=None, metrics=None).run(data)

# earned: the general name covers the specific case, no extra machinery
def transform(data: list[dict]) -> list[dict]:
    return [normalize(row) for row in data]

The specific version is also the general one: any future step is a new function, composed (lesson 0016). The framework added configuration (lesson 0029), concurrency, and retries — none of which the one case needs.

The test, from Ousterhout: does the generality make the current problem simpler? If the general module is harder to use for today's case than the specific one would be, the generality is speculative. Generalize only when the second use case is real — then the general shape is usually visible (rule of three again).

Worked example: the export framework that was bypassed

Product asks for a CSV export of returns. The engineer proposes an Exporter framework: pluggable formats, streaming, configurable columns, so that "adding XLSX later is one class".

The senior designer's first move is to sort the decisions by reversibility, because that is the axis on which this trade actually turns. Three decisions are hiding in one ticket. The function signature has one caller and is free to change. The file format is written, downloaded and forgotten, so nobody is holding an old one. The stored per-tenant export configuration is neither: it is persisted, so every change to its shape is a migration across every tenant. The question they ask is "which of these can I not take back?" — and the answer is only the third.

So the framework is rejected, with a number attached. It is roughly 380 lines and five new concepts, read by everyone who touches export for as long as it exists. The second format arrived nine months later — and wanted a workbook rather than a stream of rows, so it did not fit the framework's row-at-a-time assumption anyway. The machinery was paid for over nine months and then bypassed. That is the characteristic failure of speculative generality: not that the future never came, but that it came in a shape the guess did not cover.

What shipped was one 30-line function. When XLSX arrived it became a second function and a two-line dispatch — about 75 lines in total, with the two formats' differences visible rather than dissolved into a shared shape they do not share (lesson 0028):

def export_returns(rows: list[ReturnRecord], fmt: str) -> bytes:
    if fmt == "csv":
        return _to_csv(rows)          # a stream of rows
    if fmt == "xlsx":
        return _to_xlsx(rows)         # a workbook: genuinely a different shape
    raise UnsupportedFormat(fmt)

Two branches and two honest functions. When a third format arrives and all three share a real step — say, redacting personal fields before writing — extract that step. Not the framework.

The rule the team wrote down afterwards is the one worth stealing: generalise code on the second real case; design persisted shapes and public contracts for the third. The two halves differ only in what it costs to be wrong.

When this is the wrong move

Pay for generality up front at published boundaries — public APIs, wire formats, persisted schemas, plugin contracts — where the cost of being wrong is everyone else's migration rather than your afternoon. Pay for it when a second consumer already exists and is dated. And accept that a library has a larger generality budget than an application, because serving callers you have not met is its whole job: the same optional parameter that is speculative in your service is the reason someone can adopt your package without forking it.

Skill: earned or speculative?

Practice on your own code

Find a module with parameters or machinery no caller uses (defaults never overridden, hooks never hooked, config from lesson 0029 that's always the same). Remove the machinery — make the specific case the whole module — and check that every caller got simpler.

In the lab. The phase-3 checkpoint gives you the returns-resolution service with a configurable "resolution strategy" registry holding exactly one strategy. You strip the machinery, then argue the counter-case: which one of its shapes is persisted, and therefore should keep its version field.

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 6 "General-Purpose Modules Are Deeper": the simplification test this lesson uses.
• "Simple Made Easy", Hickey — the distinction between complexity carried and complexity deferred.
• Refactoring, Fowler — the "speculative generality" smell entry.
• "Hyrum's Law" — the one-sentence primary statement of why a published interface is not cheap to narrow later, whatever the contract says.
• Watch: ArjanCodes YouTube — search "YAGNI" or "simplicity".
• Next module: lesson 0031 — System Trade-Offs.
• Reference: Trade-offs — generality vs specificity; glossary — speculative generality.

Bring a never-overridden parameter to your agent-teacher and de-generalize it together.