One level of abstraction

A function mixes levels when business policy and machine detail share the same body. “High level” is what the system decides — charge, retry, reject, notify. “Low level” is how a machine does a mechanical thing — divide milliseconds to get days, concatenate a SQL string, zero-pad a number, format a date. These are different altitudes of thought. When they’re stacked in one function, the reader has no choice but to fly the whole altitude range on every line.

function chargeSubscription(sub: Subscription, now: number): void {
  // high level: the decision
  if (sub.status === "past_due") {
    // low level: byte/date math, inline, mid-sentence
    const daysLate = Math.floor((now - sub.lastPaidAt) / 86_400_000);
    if (daysLate > 7) {
      // low level: hand-built SQL
      db.exec(
        `UPDATE subs SET charged_at=${now} WHERE id='${sub.id}'`
      );
      // high level again: the action
      gateway.charge(sub.cardToken, sub.amountCents);
    }
  }
}

To learn the policy — past due, more than 7 days, then charge — you had to read and mentally discard the 86_400_000, the SQL, and their syntax. That discarding is the cost.

The stepdown rule: each function should read as a sequence of statements one level below it. Robert Martin’s formulation is that a program reads top-down, like prose: every function is followed by the functions one level lower, so you can descend one step of abstraction at a time. Inside a function, that means its statements should all sit at roughly the same altitude, each delegating the next “how” downward. The top function tells the story; the named calls hold the details.

function chargeSubscription(sub: Subscription, now: number): void {
  if (!isPastDue(sub)) return;
  if (daysOverdue(sub, now) <= GRACE_DAYS) return;
  markCharged(sub, now);
  gateway.charge(sub.cardToken, sub.amountCents);
}

Now the body is the policy and only the policy. daysOverdue and markCharged are promises — “there’s a how here, but it’s not the decision; descend if you care.” A reader skimming for when do we charge gets the answer in four lines and never sees a millisecond constant.

Extraction is the move, and the name is the payload. Pulling the millisecond math into daysOverdue only helps because the name says what the detail means at the level above. The reader of chargeSubscription trades Math.floor((now - sub.lastPaidAt) / 86_400_000) for the word daysOverdue — a phrase in the language of the policy. The detail still exists; it has just been moved one level down and given a label the caller can read at its altitude.

const MS_PER_DAY = 86_400_000;

function daysOverdue(sub: Subscription, now: number): number {
  return Math.floor((now - sub.lastPaidAt) / MS_PER_DAY);
}

function markCharged(sub: Subscription, now: number): void {
  // the SQL detail lives here, at the data-access level, not in the policy
  db.update("subs", { id: sub.id }, { charged_at: now });
}

A bad name defeats the whole exercise: helper1 or doStuff makes the caller descend anyway to find out what happened. The extraction buys skimmability only in proportion to how well the name describes the detail in the caller’s vocabulary.

The failure mode: over-applying shatters reading into a maze of one-line indirections. The stepdown rule is a reading aid, not a line-count target. If you extract until every two-line fragment is its own function, the reader who does want the detail must now hop through five files to reassemble one thought, and the policy function calls names so fine-grained they restate the code instead of summarising it.

// Over-extracted: each call hides almost nothing, so the reader
// must chase every name to learn anything — net reading cost UP.
function chargeSubscription(sub: Subscription, now: number): void {
  if (shouldSkipBecauseNotPastDue(sub)) return;
  if (isStillWithinGrace(sub, now)) return;
  performTheChargeBookkeeping(sub, now);
  invokeThePaymentGateway(sub);
}
function invokeThePaymentGateway(sub: Subscription): void {
  gateway.charge(sub.cardToken, sub.amountCents); // one line, wrapped for no gain
}

invokeThePaymentGateway adds a hop without adding a concept — the original gateway.charge(...) was already at policy level and already self-describing. The test isn’t “is this function short” but “does each extraction name a concept the caller genuinely wants to think in?” Extract a detail when its mechanism is noise at the level above; inline it when the name would just echo the single call it wraps. The stepdown should aid reading, not fragment it.