💬 «Хороший код сам себя документирует»? Миф или реальность?

В мире программирования существует почти религиозный спор о комментариях в коде. С одной стороны — адепты «чистого кода», которые утверждают, что комментарии — это признак слабости и недостаточно выразительного кода. С другой — прагматики, которые знают, что без комментариев некоторые участки кода превращаются в минное поле.

Давайте разберёмся, кто прав, и почему я убеждён, что комментарии — это один из самых недооценённых инструментов разработчика.

Миф № 1: Хороший код не нуждается в комментариях

Это самое популярное заблуждение. Да, код должен быть читаемым. Названия переменных и функций должны быть говорящими. Но код отвечает на вопрос «что» он делает, а не «почему» он это делает.

Представьте, что вы видите такой код:

if (user.level < 5) {
  user.applyDiscount(0);
}

Код понятен: если уровень пользователя меньше 5, скидка не применяется. Но почему?

А теперь с комментарием:

// По бизнес-требованиям, скидки доступны только пользователям,
// достигшим 5-го уровня, чтобы мотивировать их к активности.
if (user.level < 5) {
  user.applyDiscount(0);
}

Теперь всё встало на свои места. Комментарий объясняет бизнес-логику, которую невозможно выразить через названия переменных.

Миф № 2: Комментарии быстро устаревают

Да, такое случается. Разработчик меняет логику, а комментарий забывает обновить. Но это проблема не комментариев, а дисциплины.

Когда вы вносите изменения в код, вы же обновляете тесты? Иначе они упадут. Относитесь к комментариям так же, как к тестам: это неотъемлемая часть кодовой базы, которую нужно поддерживать в актуальном состоянии.

Совет: Сделайте обновление комментариев частью вашего процесса код-ревью. Видите устаревший комментарий? Попросите автора его исправить.

Когда комментарии действительно нужны?

Я не призываю комментировать каждую строчку. Это создаёт визуальный шум и отвлекает. Но есть ситуации, когда комментарии бесценны:

1. Объяснение бизнес-логики

Как в примере выше. Если в коде есть неочевидное правило, которое пришло от менеджеров или аналитиков, задокументируйте его.

2. Объяснение «костылей» и хаков

Иногда нам приходится писать неидеальный код. Например, чтобы обойти баг во внешней библиотеке или справиться с неожиданным поведением API.

// Временное решение: API иногда возвращает 'null' вместо пустого массива.
// Ждём исправления на бэкенде (задача #12345).
const data = response.data || [];

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

3. Предупреждения о последствиях

Если изменение функции может что-то сломать в другом месте, оставьте предупреждение.

// ВНИМАНИЕ: Эту функцию использует модуль аналитики.
// Перед изменением убедитесь, что не сломаете отправку событий.
function calculateTotalPrice(items) {
  // ...
}

4. TODO-заметки

Оставляйте заметки для себя и команды о том, что нужно улучшить.

// TODO: Рефакторинг. Этот алгоритм слишком медленный (O(n^2)).
// Нужно переписать с использованием хэш-таблицы.

JSDoc и другие генераторы документации

Инструменты вроде JSDoc — это прекрасно. Они помогают генерировать документацию по API ваших функций. Но они не заменяют обычные комментарии. JSDoc описывает, что принимает и возвращает функция, но редко объясняет, почему она работает именно так.

Используйте их вместе: JSDoc для описания контракта функции, а внутри — обычные комментарии для объяснения сложной логики.

Вывод: относитесь к комментариям как к заботе

Хорошие комментарии — это не признак плохого кода. Это признак заботы о коллегах и о себе в будущем. Вы оставляете хлебные крошки, которые помогут другим (и вам самим через полгода) быстрее разобраться в проблеме.

Так что в следующий раз, когда напишете неочевидный код, не ленитесь. Потратьте 30 секунд и добавьте комментарий. Ваша команда скажет вам спасибо.