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

Открой любой код, который тебе написал ИИ. Почти наверняка там найдётся что-то такое:
// увеличиваем счётчик на 1
count = count + 1
Комментарий есть. Пользы — ноль. Он пересказывает то, что и так видно из строчки ниже. А вот то, что действительно пригодилось бы через месяц, в нём нет. Давай разберёмся, что такое комментарий и каким он должен быть.
Что такое комментарий
Комментарий — это текст в коде, который программа полностью пропускает. Он для людей, а не для компьютера. Заметка на полях.
У каждого языка свой значок, с которого начинается комментарий:
// JavaScript, TypeScript, Swift, Kotlin — одна строка
/* несколько строк
тоже можно */
# Python, Ruby, Bash — решётка
<!-- HTML — вот так -->
Всё, что после значка, программа не читает. Можешь написать там что угодно — хоть по-русски, хоть стихи. На работу кода это не повлияет.
Что писать в комментарии: «почему», а не «что»
Вот главная мысль статьи. Код сам отвечает на вопрос «что происходит» — его можно прочитать. А на вопрос «почему именно так» код не ответит никогда.
Сравни:
// ждём 300 мс
await sleep(300)
// сервер оплаты отклоняет запросы чаще 3 в секунду — поэтому пауза
await sleep(300)
Первый комментарий бесполезен. Второй спасает. Без него через месяц ты (или ИИ) увидишь «лишнюю» паузу, удалишь её ради скорости — и оплата начнёт падать.
Хороший комментарий объясняет то, чего нет в коде:
- причину странного решения — «так, потому что…»;
- ловушку — «не меняй порядок, иначе…»;
- ссылку на источник — задачу, документацию, баг;
- временную заплатку — «убрать, когда сервер починят».
Почему комментарии врут
Смотри, неприятная штука. Код проверяет компьютер: сломал — сразу видно. Комментарий не проверяет никто.
Поэтому он стареет. Код поправили, а заметку над ним забыли. И теперь она уверенно описывает то, чего уже нет. Устаревший комментарий хуже, чем никакого: он сбивает с толку и тебя, и ИИ.
Отсюда два правила:
- Меньше комментариев — меньше вранья. Если код можно сделать понятным через хорошее имя переменной, лучше так.
pauseForPaymentLimit()понятнее, чемsleep(300)с комментарием. - Меняешь код — проверь заметку над ним. Это стоит одной секунды.
Про закомментированный код отдельно. Строчки, которые «выключили на всякий случай», засоряют проект. Смело удаляй их: git помнит всю историю, и старую версию всегда можно вернуть.
Как управлять ИИ через комментарии
А вот здесь комментарии становятся суперсилой. Для ИИ они не просто заметки — это инструкции.
Комментарий как заказ. Напиши в пустом месте файла, что тебе нужно, — и автодополнение в редакторе допишет код под него:
// функция: принимает список заказов, возвращает сумму только оплаченных
Комментарий как забор. ИИ-агент читает файл перед правкой. Предупреждение прямо в коде работает лучше, чем просьба в чате, которую он забудет:
// ВАЖНО: не менять формат даты — его читает мобильное приложение
Для правил на весь проект есть отдельный файл — AGENTS.md. А комментарий хорош для точечных предупреждений у конкретной строчки.
Уборка шума. Когда ИИ напишет код, попроси его навести порядок в заметках:
Добавь комментарииПройдись по этому файлу. Удали комментарии, которые пересказывают код. Оставь и допиши только те, что объясняют ПОЧЕМУ: причины неочевидных решений, ловушки, временные заплатки. Закомментированный код удали.Кстати, умение отличать полезный комментарий от шума — часть большого навыка: читать код, который написал ИИ.
Замедляют ли комментарии программу?
Нет. Программа их просто пропускает. А на сайтах сборщик вообще вырезает комментарии перед выкладкой, так что посетитель их не скачивает.
На каком языке писать комментарии?
На том, на котором читает команда. Для себя — хоть по-русски. Для открытого проекта принято по-английски.
Сколько комментариев нормально?
Нет правильного числа. Если без заметки строчку легко понять не так — пиши. Если она дублирует код — не пиши.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





