Когда комментарии врут

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

// increment i by one
i = i + 1;

// set the user's name to the given name
user.name = name;

// loop over all the items
for (const item of items) { /* ... */ }

Ни один из них не сообщает читателю ничего, чего код уже не кричит. Хуже: когда i = i + 1 позже становится i += 2, комментарий теперь неверен, и ты сфабриковал ложь из того, что было просто бесполезным. Лечение не в том, чтобы написать лучший пересказ — а в том, чтобы удалить комментарий и, если строка была неясна, сделать яснее код (имя получше, функцию поменьше). Код — источник истины; не перефразируй его.

Устаревший комментарий — это баг без теста, который его поймал бы. Это опасное семейство, потому что оно не просто тратит взгляд — оно с полной уверенностью отправляет тебя по неверному пути.

// timeout is 30 seconds
const TIMEOUT_MS = 10_000;

// NOTE: assumes the list is already sorted
function median(xs: number[]): number {
  return xs[Math.floor(xs.length / 2)]; // returns the wrong element if xs is NOT sorted
}

Первый комментарий противоречит литералу рядом с ним; читатель, доверившийся прозе, считает с неверным числом. Второй хуже — он документирует предусловие (already sorted), которое ничто не обеспечивает, поэтому функция молча вернёт мусор в тот день, когда вызывающий о нём забудет. Комментарии вроде этих гниют именно потому, что сидят рядом с кодом, который меняется без них. Каждый оставленный комментарий — это бремя сопровождения, которое ты подписался обновлять вручную, вечно, и никакой компилятор тебе не напомнит.

Закомментированный код — мёртвый груз; удали его, система контроля версий помнит. Блок кода, «оставленный на всякий случай», обёрнутый в // или /* */, — один из самых частых и наименее оправданных комментариев.

function price(order: Order): number {
  // const tax = subtotal * 0.2;          // old flat rate
  // return subtotal + tax;
  // return subtotal + applyOldDiscount(subtotal);
  return subtotal + taxFor(subtotal, order.region);
}

Он не отвечает ни на один вопрос читателя. Это следующее, что отгрузят? Запасной путь? Заброшенный эксперимент? Никто не знает, поэтому все его оставляют — и он накапливается, гния бок о бок с живым кодом, путая каждый будущий поиск и ревью. Оригинал не потерян: git log -p и git blame хранят каждую строку, которую ты когда-либо удалял, вместе с коммитом, объясняющим почему. Удаление закомментированного кода ничего не теряет и убирает шум. Сохранение его ничего не сберегает и добавляет сомнение.

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

// Stripe rounds half-up; we must match their cents exactly or the
// reconciliation job flags a 1-cent mismatch and pages on-call.
const cents = Math.round(amount * 100);

// DO NOT parallelise: the upstream API rejects concurrent writes
// to the same account with a 409 we can't retry cleanly.
for (const tx of txs) await post(tx);

// Binary search instead of indexOf: this runs per keystroke on a
// 50k-row list; linear scan dropped input latency below 60fps.
const i = lowerBound(rows, query);

Каждый из них заслуживает своего места. Ни один не повторяет код; каждый улавливает обоснование, которое будущему сопровождающему пришлось бы заново открывать, что-нибудь сломав. Лакмусовая бумажка: если бы ты удалил комментарий, смог бы грамотный читатель восстановить информацию из одного кода? Для что/как — да, значит комментарий это шум. Для почему (тот самый 409, сверка, бюджет в 60fps) — нет, значит комментарий делает реальную работу. Предупреждения о последствии, закодированное намерение, которое система типов уловить не может, и маркеры // TODO(JIRA-1234): …, привязанные к тикету, — всё это варианты одной законной задачи: записать то, что код выразить не может.