Комментарии должны быть содержательными
Воспринимайте комментарии как описание вашей системы. Будьте готовы к тому, что ваши комментарии будут извлечены роботом из текста исходника и оформлены в виде технического руководства. Комментарии к классам станут одной частью описания, сигнатуры методов - другой частью, аргументы методов - третьей, реализации методов - четвёртой. Все эти части должны слиться в единое целое и информировать удалённого в пространстве и времени читателя о том, что именно вы сделали и почему.
Документируйте принятые решения
Комментарии должны документировать принятые решения. Каждый раз, когда вы выбрали какой-либо способ реализации, поставьте комментарий, повествующий о том, что вы выбрали и почему. Для археологов это станет самой полезной информацией.
Используйте заголовки
Используйте систему автоматической генерации документации, такую как PHPDoc. В других разделах этого документа будут описаны приёмы использования PHPDoc для документирования классов и методов.
Структура заголовков обеспечивает их анализ и извлечение из исходника -структурированные заголовки уже приносят пользу, в отличие от обычных. Поэтому рекомендуется потратить немного времени на их заполнение - и документирование вам больше не понадобится.
Стиль комментариев
Каждая часть проекта имеет свой особый стиль комментариев.
Явно указывайте на gotchas ["ловушки" в коде]
Комментируйте как любые изменения переменных, не совсем вписывающиеся в нормальный ход программы, так и все конструкции, которые могут натворить дел при изменении кода. Для явного указания на проблемные или потенциально проблемные куски кода используйте встроенные зарезервированные слова.