Комментарии и решения

← К концепции

Объясняем причину

Полезный комментарий фиксирует инвариант, неочевидное ограничение или архитектурное решение. Не пересказываем очевидный код. Сохраняем существующие комментарии, пока соответствующее решение не изменилось.

// Сохраняем исходный снимок, пока все программы не записаны успешно
await import_programs(snapshot)

Выбираем имена и контракты, с которыми поведение понятно без комментария. Ownership и публичные гарантии документируем рядом с владельцем. Операционные команды и настройки развёртывания находятся в эксплуатационной документации, а не в интерфейсе продукта.