Что такое «Комментарий в коде»
Код отвечает на вопрос «что делается», а комментарий нужен там, где из кода не видно «почему». Почему цена приводится к числу, почему здесь пауза в секунду, почему нельзя убрать странную проверку — через год этого не помнит даже автор. Хороший комментарий экономит часы следующему разработчику, плохой пересказывает строку под ним и устаревает при первой правке.
Виды комментариев в PHP
// Обмен с 1С присылает цену строкой с запятой — приводим к числу
$price = (float) str_replace(',', '.', $raw['PRICE']);
/**
* Возвращает активные заказы пользователя.
*
* @param int $userId ID пользователя
* @return Order[] пустой массив, если заказов нет
*/
function getActiveOrders(int $userId): array { /* … */ }
Кроме // и блочных /* … */, PHP понимает однострочные комментарии с #, но с PHP 8 запись #[...] означает уже не комментарий, а атрибут. Блок, начинающийся с /**, — это PHPDoc: по нему редакторы кода подсказывают типы и параметры, а генераторы собирают справочник. Описание системы целиком — отдельная задача, о ней статья про документацию.
Что стоит комментировать, а что нет
- Стоит: причины неочевидных решений, обходы ошибок сторонних библиотек со ссылкой на задачу, бизнес-правила («скидка не суммируется с промокодом по договору с поставщиком»), предупреждения («не менять порядок — от него зависит выгрузка»).
- Не стоит: пересказ кода вроде
$i++; // увеличиваем i, закомментированные куски старого кода — для истории есть система контроля версий, — а также подписи «изменил Иванов», которые тоже видны в истории. - Метки
TODOиFIXMEполезны, если к ним действительно возвращаются; редакторы и линтеры умеют собирать их в список.
Серверные комментарии и комментарии в разметке
Комментарии в PHP-файлах остаются на сервере: посетитель их не увидит. А комментарии в HTML, CSS и JavaScript попадают в браузер и доступны любому через просмотр кода страницы. Поэтому в шаблонах не оставляют паролей, внутренних адресов и пометок вроде «временно отключили проверку» — если пометка нужна, её делают PHP-комментарием. И к этой теме не относятся комментарии посетителей под записями: это отдельная функция CMS.
Связанные термины
Обновлено: 10 октября 2026

