steelmorgan/semantic-code-comments

Семантические комментарии в коде

Хороший комментарий объясняет почему, а не что. Имена, структура и выражения уже показывают действие кода; комментарий нужен для бизнес-смысла, ограничений, компромиссов и скрытых инвариантов.

Принцип

Код пишется один раз, а читается много раз. Если будущий читатель спросит «почему так?», «что сломается, если убрать?», «какое бизнес-правило здесь защищено?» — нужен семантический комментарий.

Что комментировать / что НЕ комментировать

| Комментировать (почему) | НЕ комментировать (что) | |-------------------------|-------------------------| | Неочевидные бизнес-правила | Пересказ кода (// складываем A и B) | | Защиту от внешних сбоев и краевых случаев | Очевидные операции (// увеличиваем счётчик) | | Workaround и компромиссы | | | Скрытые инварианты и порядок вызовов | | | Причины отказа от очевидного решения | | | Магические числа и константы | |

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

Хорошо:

// Скидку применяем только после подтверждения лимита, потому что договор
// может запрещать ретроспективное изменение цены.
Если ЛимитПодтвержден И ДоговорРазрешаетИзменениеЦены Тогда

Плохо:

// Плохо: складываем A и B.
Сумма = A + B;

SHOULD

• Перед нетривиальным блоком сложной логики дать краткое объяснение назначения блока.
• В начале процедуры добавить комментарий назначения, если оно не следует из имени.
• Ссылаться на спецификацию, ADR или задачу, когда без внешнего контекста причина решения непонятна.
• Объяснять ограничения внешних систем, платформы, библиотек и данных.
• Комментировать намеренно странный код: почему он выглядит необычно и что сломается при «упрощении».

Как формулировать

| Хорошо | Плохо | |--------|-------| | "Не используем X, потому что Y" | "Здесь X" | | "Защита от пустого ответа внешнего сервиса" | "Проверяем значение" | | "Если убрать, нарушится инвариант периода" | "Не трогать" | | "Сначала заполняем кэш, потому что следующий запрос читает его" | "Заполняем кэш" |

Связь с разметкой изменений

agent-code-marking показывает, кто и когда изменил код; semantic-code-comments объясняет, почему код устроен именно так. Маркеры дают аудит, комментарии — смысл.

depends_on:

• agent-code-marking