Что такое «Комментарии в коде»
Код пишут один раз, а читают десятки раз: при доработке, поиске ошибки, передаче проекта другому разработчику. Комментарий сохраняет контекст, которого нет в самом коде, — почему выбран обходной путь, какой баг браузера здесь лечится, откуда взялось странное число. Хороший комментарий отвечает на вопрос «зачем», а не пересказывает очевидное «что».
Синтаксис в разных языках
<!-- 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

