foundation

Comments that explain why, not what

Используйте comments, чтобы сохранить intent, constraints, trade-offs и unexpected context, а не пересказывать obvious code.

Комментарии фиксируют intent, constraints, неочевидные компромиссы, regulatory requirements и ссылки на инциденты — не пересказывают очевидный код (`i++ // increment i`). Хорошие комментарии стареют медленно: объясняют решения, которые код не выразит.

Сначала выразительный код; комментарий, когда why потеряется при rename.

На интервью: улучшите misleading или лишние комментарии у хитрого workaround.

Типовые ошибки: устаревшие комментарии врут; закомментированный код годами; TODO без owner или тикета.

Компромисс — поддержка комментариев против скорости onboarding в surprising logic.

Чеклист:

Решения и constraints.
Удаляйте неверные и obsolete.
Ссылка на ticket/spec при необходимости.