Самодокументируемый код

Комментарий, говорящий, что делает код, — это имя, которое ты ещё не написал. Когда ты ловишь себя на том, что пишешь // проверить, может ли пользователь редактировать этот пост над клубком булевых условий, ты уже назвал концепцию — в комментарии. Код под ним — безымянная реализация. Извлечение его в canEdit(user, post) переносит имя из комментария (который компилятор игнорирует и никто не рефакторит) в сигнатуру функции (которую компилятор проверяет и каждый вызывающий читает).

// before: имя живёт в комментарии, который компилятор не может проверить
// check if the user can edit this post
if (user.id === post.authorId || user.role === "admin") { /* ... */ }

// after: имя живёт в коде, который читает сам себя
if (canEdit(user, post)) { /* ... */ }

Комментарий и условие могут разойтись; имя функции и её тело — нет. Что теперь несёт структура, а не проза.

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

// before — комментарии пересказывают блок, который делает слишком много
function publish(post: Post) {
  // validate the post is ready
  if (!post.title || !post.body) throw new Error("incomplete");
  if (post.body.length < 100) throw new Error("too short");
  // render markdown to html and strip scripts
  const html = sanitize(renderMarkdown(post.body));
  // write to the store and bump the index
  store.save({ ...post, html, status: "live" });
  searchIndex.add(post.id, post.title);
}

// after — каждый комментарий-шаг становится именем, которое читает само себя
function publish(post: Post) {
  assertPublishable(post);
  const html = renderSafeHtml(post.body);
  persistAndIndex(post, html);
}

Второй publish читается так же, как читались комментарии-шаги, — только имена теперь проверены системой типов и переиспользуются везде, где повторяется тот же шаг. Комментарии стали оглавлением, которое функция всегда хотела иметь.

Объясняющая переменная превращает загадочное выражение в предложение — функция не нужна. Извлечение — не только про функции. Когда условию или подвыражению нужен // потому что …, чтобы быть читаемым, именование промежуточного значения часто несёт смысл дешевле, чем целая функция.

// before: комментарий подпирает нечитаемое условие
// only retry on transient network failures, not 4xx
if (err.code === "ECONNRESET" || err.code === "ETIMEDOUT" || (err.status >= 500 && err.status < 600)) {
  retry();
}

// after: имена заставляют условие заявить собственное намерение
const isNetworkReset = err.code === "ECONNRESET" || err.code === "ETIMEDOUT";
const isServerError = err.status >= 500 && err.status < 600;
const isTransient = isNetworkReset || isServerError;
if (isTransient) retry();

Комментарий // retry только на временных сбоях теперь избыточен — if (isTransient) retry() говорит это в коде. Объясняющая переменная — самое лёгкое из доступных извлечений: ни нового вызова, ни прыжка в другой файл, просто имя.

Комментарии, которые выживают, — это ПОЧЕМУ, и самодокументируемый код делает их заметнее, а не реже. Когда что несут имена, остаются только те комментарии, которые код структурно выразить не может: почему было принято неожиданное решение, ссылка на тикет или RFC, который его оправдывает, неочевидное ограничение, обходной приём для бага в чём-то, что ты не контролируешь. Это золото, потому что никаким переименованием их не вывести из кода — они кодируют контекст, живущий вне него.

// ПОЧЕМУ выживает: код не может объяснить себя сам
// Stripe rounds half-up; we round half-even to match Finance's ledger.
// Changing this silently re-bills every subscription. See FIN-2231.
const cents = bankersRound(amount * 100);

// Safari <16 throws on structuredClone of a Blob; fall back. (bug: WK-204931)
const copy = canStructuredClone ? structuredClone(v) : deepCopy(v);

«Самодокументируемый» не значит «без комментариев». Это значит, что код несёт что так ясно, что выжившие почему-комментарии выделяются, а не тонут в шуме вроде // increment i. Senior-ревьюер читает файл, и каждый оставшийся комментарий заслуживает своё место.