A Philosophy of Software Design — выпуск 3

Третий выпуск посвящён документации и naming. Self-documenting code не отменяет комментарии: код показывает действие машины, но редко сохраняет причины, ограничения и отброшенные альтернативы. Если для понимания interface приходится читать implementation, абстракция протекла.

Участники разбирают отговорки: нет времени, комментарии устареют, плохой текст бесполезен. Автор считает их design investment: восстановление контекста спустя годы дороже. High-level comments меняются реже деталей и объясняют поведение, договорённости и неочевидные связи.

Есть четыре уровня: interface, data structure, implementation и cross-module context. Текст не пересказывает код, а добавляет то, чего из него не вывести. Naming решает ту же задачу: точное consistent имя строит модель читателя. Два значения block показывают, как расплывчатое слово расширяет поиск бага.

Write Comments First делает документацию инструментом design. Сначала описываются contract, параметры, return value, exceptions и логика, затем пишется implementation. Черновик выявляет неудобный interface раньше кода. При изменении системы комментарии пересматривают вместе с реализацией; high-level текст требует правок реже.