Глава 19. Несколько комментариев по комментариям

Комментарии должны быть содержательными

Воспринимайте комментарии как описание вашей системы. Будьте готовы к тому, что ваши комментарии будут извлечены роботом из текста исходника и оформлены в виде технического руководства. Комментарии к классам станут одной частью описания, сигнатуры методов - другой частью, аргументы методов - третьей, реализации методов - четвёртой. Все эти части должны слиться в единое целое и информировать удалённого в пространстве и времени читателя о том, что именно вы сделали и почему.

Документируйте принятые решения

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

Используйте заголовки

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

Структура заголовков обеспечивает их анализ и извлечение из исходника -структурированные заголовки уже приносят пользу, в отличие от обычных. Поэтому рекомендуется потратить немного времени на их заполнение - и документирование вам больше не понадобится.

Стиль комментариев

Каждая часть проекта имеет свой особый стиль комментариев.

Явно указывайте на gotchas ["ловушки" в коде]

Комментируйте как любые изменения переменных, не совсем вписывающиеся в нормальный ход программы, так и все конструкции, которые могут натворить дел при изменении кода. Для явного указания на проблемные или потенциально проблемные куски кода используйте встроенные зарезервированные слова.