Единый уровень абстракции

Функция смешивает уровни, когда бизнес-политика и машинная деталь делят одно тело. «Высокий уровень» — это что система решает: списать, повторить, отклонить, уведомить. «Низкий уровень» — это как машина делает механическую вещь: поделить миллисекунды, чтобы получить дни, склеить SQL-строку, дополнить число нулями, отформатировать дату. Это разные высоты мысли. Когда они сложены в одной функции, читателю не остаётся выбора, кроме как пролетать весь диапазон высот на каждой строке.

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);
    }
  }
}

Чтобы выучить политику — просрочка, больше 7 дней, тогда списать, — тебе пришлось прочитать и мысленно отбросить 86_400_000, SQL и их синтаксис. Это отбрасывание и есть цена.

Правило понижения: каждая функция должна читаться как последовательность операторов на один уровень ниже неё. Формулировка Роберта Мартина в том, что программа читается сверху вниз, как проза: за каждой функцией следуют функции на один уровень ниже, чтобы можно было спускаться по одному шагу абстракции за раз. Внутри функции это значит, что её операторы должны находиться примерно на одной высоте, каждый делегируя следующее «как» вниз. Верхняя функция рассказывает историю; именованные вызовы держат детали.

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);
}

Теперь тело — это политика и только политика. daysOverdue и markCharged — это обещания: «тут есть какое-то как, но это не решение; спустись, если интересно». Читатель, обозревающий когда мы списываем, получает ответ в четырёх строках и ни разу не видит миллисекундную константу.

Выделение — это ход, а имя — полезная нагрузка. Вынос миллисекундной математики в daysOverdue помогает только потому, что имя говорит, что эта деталь означает на уровне выше. Читатель chargeSubscription меняет Math.floor((now - sub.lastPaidAt) / 86_400_000) на слово daysOverdue — фразу на языке политики. Деталь всё ещё существует; её просто переместили на уровень ниже и дали ярлык, который вызывающий может прочитать на своей высоте.

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 });
}

Плохое имя сводит на нет всё упражнение: helper1 или doStuff всё равно заставляет вызывающего спуститься, чтобы узнать, что произошло. Выделение покупает обозримость только в той мере, в какой имя описывает деталь в словаре вызывающего.

Режим отказа: чрезмерное применение разбивает чтение на лабиринт однострочных косвенностей. Правило понижения — это подспорье для чтения, а не цель по числу строк. Если выделять, пока каждый двухстрочный фрагмент не станет своей функцией, то читателю, который всё-таки хочет деталь, придётся прыгать по пяти файлам, чтобы собрать одну мысль, а функция-политика вызывает имена настолько мелкозернистые, что они пересказывают код, а не резюмируют его.

// 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 добавляет прыжок, не добавляя концепции — исходный gateway.charge(...) уже был на уровне политики и уже самоописателен. Критерий не «короткая ли эта функция», а «называет ли каждое выделение концепцию, в которой вызывающий действительно хочет думать?» Выделяй деталь, когда её механизм — шум на уровне выше; встраивай её обратно, когда имя лишь повторит единственный вызов, который оно оборачивает. Понижение должно помогать чтению, а не дробить его.