Что такое…

Что такое комментарий в коде — и почему ИИ пишет их неправильно

Иллюстрация: механизм с шестерёнками, а рядом на ниточках — заметки на полях

Открой любой код, который тебе написал ИИ. Почти наверняка там найдётся что-то такое:

// увеличиваем счётчик на 1
count = count + 1

Комментарий есть. Пользы — ноль. Он пересказывает то, что и так видно из строчки ниже. А вот то, что действительно пригодилось бы через месяц, в нём нет. Давай разберёмся, что такое комментарий и каким он должен быть.

Что такое комментарий

Комментарий — это текст в коде, который программа полностью пропускает. Он для людей, а не для компьютера. Заметка на полях.

У каждого языка свой значок, с которого начинается комментарий:

// JavaScript, TypeScript, Swift, Kotlin — одна строка
/* несколько строк
   тоже можно */
# Python, Ruby, Bash — решётка
<!-- HTML — вот так -->

Всё, что после значка, программа не читает. Можешь написать там что угодно — хоть по-русски, хоть стихи. На работу кода это не повлияет.

Что писать в комментарии: «почему», а не «что»

Вот главная мысль статьи. Код сам отвечает на вопрос «что происходит» — его можно прочитать. А на вопрос «почему именно так» код не ответит никогда.

Сравни:

// ждём 300 мс
await sleep(300)
// сервер оплаты отклоняет запросы чаще 3 в секунду — поэтому пауза
await sleep(300)

Первый комментарий бесполезен. Второй спасает. Без него через месяц ты (или ИИ) увидишь «лишнюю» паузу, удалишь её ради скорости — и оплата начнёт падать.

Хороший комментарий объясняет то, чего нет в коде:

  • причину странного решения — «так, потому что…»;
  • ловушку — «не меняй порядок, иначе…»;
  • ссылку на источник — задачу, документацию, баг;
  • временную заплатку — «убрать, когда сервер починят».

Почему комментарии врут

Смотри, неприятная штука. Код проверяет компьютер: сломал — сразу видно. Комментарий не проверяет никто.

Поэтому он стареет. Код поправили, а заметку над ним забыли. И теперь она уверенно описывает то, чего уже нет. Устаревший комментарий хуже, чем никакого: он сбивает с толку и тебя, и ИИ.

Отсюда два правила:

  1. Меньше комментариев — меньше вранья. Если код можно сделать понятным через хорошее имя переменной, лучше так. pauseForPaymentLimit() понятнее, чем sleep(300) с комментарием.
  2. Меняешь код — проверь заметку над ним. Это стоит одной секунды.

Про закомментированный код отдельно. Строчки, которые «выключили на всякий случай», засоряют проект. Смело удаляй их: git помнит всю историю, и старую версию всегда можно вернуть.

Как управлять ИИ через комментарии

А вот здесь комментарии становятся суперсилой. Для ИИ они не просто заметки — это инструкции.

Комментарий как заказ. Напиши в пустом месте файла, что тебе нужно, — и автодополнение в редакторе допишет код под него:

// функция: принимает список заказов, возвращает сумму только оплаченных

Комментарий как забор. ИИ-агент читает файл перед правкой. Предупреждение прямо в коде работает лучше, чем просьба в чате, которую он забудет:

// ВАЖНО: не менять формат даты — его читает мобильное приложение

Для правил на весь проект есть отдельный файл — AGENTS.md. А комментарий хорош для точечных предупреждений у конкретной строчки.

Уборка шума. Когда ИИ напишет код, попроси его навести порядок в заметках:

Слабый промптДобавь комментарии
Сильный промптПройдись по этому файлу. Удали комментарии, которые пересказывают код. Оставь и допиши только те, что объясняют ПОЧЕМУ: причины неочевидных решений, ловушки, временные заплатки. Закомментированный код удали.

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

Замедляют ли комментарии программу?

Нет. Программа их просто пропускает. А на сайтах сборщик вообще вырезает комментарии перед выкладкой, так что посетитель их не скачивает.

На каком языке писать комментарии?

На том, на котором читает команда. Для себя — хоть по-русски. Для открытого проекта принято по-английски.

Сколько комментариев нормально?

Нет правильного числа. Если без заметки строчку легко понять не так — пиши. Если она дублирует код — не пиши.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →