Что такое «Комментарий в коде»

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

Виды комментариев в 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

Все термины раздела «Backend» ↗