Comments Considered Harmful in the Age of LLMs

@misc{bugayenkoblog,
  author = {Bugayenko, Yegor},
  title = {{Comments Considered Harmful in the Age of LLMs}},
  howpublished = {\url{https://www.yegor256.com}},
  year = {},
  month = {},
  note = {[Online; accessed 11-01-2026]}
}

Написание документации к коду - это боль. Не писать ее приводит к еще большему болю - мы не можем понять код. Однако, написание ее, а затем забывание об обновлении, вызывает абсолютную боль: она лжет и сбивает нас с толку. Что если мы избавимся от всех трех болей сразу: запретим все комментарии! Как мы узнаем намерение кода, если у нас нет комментариев? Мы попросим LLM объяснить нам это. Что если LLM не сможет объяснить и признается в своей неспособности? Тогда мы автоматически завалим сборку и виним автора кода. Таким образом, мы вводим новый показатель качества: Оценка интерпретируемости кода. Сборка проходит только в том случае, если эта оценка достаточно высока.

Лучшие умы в области программной инженерии давно мечтали о самодокументирующемся коде. В 1974 году Брайан Керниган и Филипп Джеймс Плаугер сказали, что “единственная надежная документация компьютерной программы - это сам код”. В 2004 году Стивен Макконнелл в Code Complete заявил, что “основной вклад в документирование на уровне кода вносится не комментариями, а хорошим стилем программирования”. В 2008 году Роберт Мартин в Clean Code предположил, что “если бы наши языки программирования были достаточно выразительными, или если бы у нас было достаточно таланта для тонкого владения этими языками для выражения наших намерений, нам не очень нужны были бы комментарии - возможно, совсем не нужны”. Они все хотели одного и того же: кода, который объясняет сам себя. Им просто не хватало инструментов для его обеспечения.

Зачем мы вообще пишем комментарии? Метод на Java из ста строк может занять часы для понимания. Маленький блок Javadoc экономит это время:

Комментарии обещают помочь нам, но терпят неудачу двумя различными способами.

Во-первых, они непонятны. Дэвид Парнас однажды сказал, что “документация, которая кажется ясной и достаточной для ее авторов, часто так же ясна, как грязь для программиста, который должен поддерживать код через шесть месяцев или шесть лет.” То, что автор считает очевидным, читатель находит загадочным.

Во-вторых, они устаревают. Будучи статическими метаданными, комментарии не развиваются автоматически вместе с кодом. Если реализация функции shortest() перестает быть рекурсивной, мы можем забыть обновить блок Javadoc. Такое небрежное отношение приводит к галлюциногенной документации, которая вызывает ошибки, нарушение доверия и потерю времени на отладку. В 1999 году Эндрю Хант и Дейв Томас в The Pragmatic Programmer предупредили, что “ненадежные комментарии хуже отсутствия комментариев вообще.” Недавнее исследование 13 проектов с открытым исходным кодом показало, что устаревшие комментарии не являются редкостью, а вполне обычным явлением.

Теперь у нас есть инструмент, который решает обе проблемы: LLM.

Вместо того чтобы писать блок Javadoc вручную, мы позволяем IDE генерировать его по требованию. LLM считывает сто строк кода, понимает их и подводит итог в одном английском предложении. Современные модели справляются с этой задачей лучше, чем большинство людей. Документация всегда свежая, потому что она генерируется из текущего кода, а не из устаревшего комментария, написанного месяцы назад.

Но мы можем пойти дальше. Мы можем интегрировать LLM в конвейер сборки и попросить его оценить Оценку Интерпретируемости Кода (CIS) каждой функции. Если модель не уверена в объяснении логики, это сигнализирует о том, что код слишком хитрый или запутанный. Компилятор может установить порог: если CIS слишком низкое, сборка завершится неудачей. Это превращает читаемость из субъективного предпочтения в объективное, измеримое качество.

Как только этот порог существует, ручные комментарии становятся не просто ненужными, а вредными. Они вносят второй источник правды, который может противоречить коду. Логичный вывод: полностью запретить их. Это заставляет разработчиков писать чистую, структурированную логику, которая по своей сути может быть интерпретирована машиной.

Роберт Мартин мечтал о более выразительных языках. Он не знал о LLM. Сегодня нам не нужны лучшие языки — нам нужен LLM, который может интерпретировать любой язык. Если LLM не может объяснить код, мы виним программиста и прекращаем сборку.

Мы думаем сделать наш экспериментальный объектно-ориентированный язык EO более ограничительным.

Translated by ChatGPT gpt-3.5-turbo/42 on 2026-01-11 at 20:46