# Правила комментирования кода в Go

Цель: читаемость и предсказуемость без “формальных” комментариев. Эти правила обязательны для разработчиков и ИИ-агентов.

## Общие принципы

- Комментарии пишутся **на английском**, если код не является публичной библиотекой для внешних пользователей.
- Комментарий объясняет **зачем/смысл/ограничения**, а не повторяет код.
- Если без комментария всё ясно — не писать. Если без комментария неясно — писать.
- Комментарии должны быть актуальными; устаревший комментарий хуже отсутствия.

## Комментарии к пакетам (package comment)

Package comment обязателен, если пакет:
- экспортирует что-то наружу;
- часть публичного API сервиса;
- содержит доменную или инфраструктурную логику.

Требования:
- размещать в `doc.go` или в начале файла пакета;
- начинать с имени пакета (`Package <name> ...`);
- описывать назначение/ответственность (не детали реализации).

## Комментарии к экспортируемым типам

Все экспортируемые типы (struct/interface/alias/enum-подобные) обязаны иметь комментарий.

Требования:
- начинать с имени типа;
- описывать роль/семантику, не перечисление полей;
- не писать “Type is a type”.

## Комментарии к экспортируемым полям структур

Экспортируемые поля комментировать обязательно, если:
- смысл не очевиден из имени;
- поле часть доменной семантики/контракта;
- поле используется во внешних API (HTTP/gRPC/events).

Комментарий должен фиксировать семантику/ограничения/допустимые значения. Очевидные технические поля (`ID`, `CreatedAt`) можно не комментировать, если однозначны.

## Комментарии к экспортируемым функциям и методам

Все экспортируемые функции/методы обязаны иметь комментарий.

Требования:
- начинать с имени функции;
- описывать что делает (не как);
- при необходимости указать побочные эффекты/ограничения/семантику ошибок (высокоуровнево, без перечисления типов).

## Комментарии к неэкспортируемому, но сложному коду

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

Фокус: объяснить **почему так**, зафиксировать инварианты/причины/последствия изменения.

## Inline-комментарии (внутри функций)

Допустимы, если логика нелинейна, много смысловых веток, есть договорённости “вне типов”.
Запрещено: комментировать каждую строку; заменять комментариями плохие имена.

## TODO и FIXME

- `TODO` только с причиной и желательно ссылкой на задачу.
- `FIXME` только для явно временного/некорректного решения.

## Комментарии и архитектурные решения

Если код реализует исключение из стандартов, архитектурный компромисс или временное решение — это обязательно фиксируется комментарием рядом с кодом (почему так и когда убрать/пересмотреть).

## Чего делать нельзя

Запрещено:

- использовать комментарии как замену плохим именам;
- оставлять комментарии “на всякий случай”;
- держать комментарии, не соответствующие текущему поведению кода;
- копировать комментарии без адаптации.
