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

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

Синтаксис в разных языках

<!-- HTML: блок акций, выводится только на главной -->
/* CSS: компенсируем высоту фиксированной шапки */
// JavaScript и PHP: однострочный комментарий
# PHP: тоже однострочный, встречается реже
/**
 * Docblock в PHP: описание функции для IDE.
 * @param int $orderId Номер заказа
 */

Блочные комментарии /* … */ работают в CSS, JavaScript и PHP. Вложить один такой блок в другой нельзя: первая же закрывающая последовательность завершит комментарий, и остаток превратится в код с ошибкой.

Что видно посетителю

Комментарии в HTML, CSS и скриптах уходят в браузер вместе со страницей. Любой может открыть исходный код и прочитать их. Отсюда реальные утечки: закомментированный блок с тестовыми ссылками, адрес служебного раздела, заметка «временный пароль». Комментарии в PHP, наоборот, остаются на сервере — интерпретатор отдаёт клиенту только результат выполнения.

При сборке фронтенда минификатор обычно вырезает комментарии, чтобы уменьшить вес файлов. Многие инструменты по умолчанию оставляют блоки вида /*! … */ и строки с @license — так сохраняют лицензии подключённых библиотек.

Чего не стоит делать

  • Хранить старый код в комментариях «на всякий случай». Для истории изменений есть система контроля версий.
  • Писать комментарии, которые расходятся с кодом. После правки функции устаревшее пояснение вводит в заблуждение сильнее, чем его отсутствие.
  • Объяснять каждую строку. Если код непонятен без подробного пересказа, его чаще стоит переписать и дать переменным говорящие имена.
  • Править чужие темы и модули, оставляя только комментарий «изменено». Такие правки теряются при обновлении — лучше выносить доработки в дочернюю тему или собственный модуль. Как это делается в Битриксе, описано в статье об обновлении 1С-Битрикс без потери доработок.

Полезная практика — помечать временные решения меткой TODO с причиной: «TODO: убрать, когда поставщик исправит формат выгрузки». Такие места легко найти поиском по проекту. Специальный вид комментария — docblock: по нему редактор кода подсказывает типы параметров, а генераторы документации собирают описание API. Аккуратные пояснения в коде — часть того, что делает разметку и таблицы стилей пригодными для поддержки.

Связанные термины

Обновлено: 10 октября 2026

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