The paper presents a VS Code module for automated creation and maintenance of C++ code documentation. Unlike existing tools, it tracks signature changes, visually highlights outdated comments, and enables one-click updates. Experimental results show a 71.5 % reduction in documentation time.

Keywords: documenting code, Visual Studio Code, abstract syntax tree, C++, artificial intelligence.

Введение

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

Однако на практике классический ручной процесс документирования сталкивается с рядом системных проблем. Во-первых, разработчики вынуждены тратить значительное время на написание и актуализацию комментариев, что часто воспринимается как второстепенная задача. Во-вторых, документация, созданная однажды, быстро устаревает, поскольку изменения в коде не сопровождаются соответствующим обновлением описаний. В результате появляются противоречивые, неполные или откровенно неверные комментарии, которые не только теряют свою полезность, но и могут вводить разработчиков в заблуждение [1].

Таким образом, целью данной работы является разработка программного модуля автоматизированного документирования программного кода (ПМ АДПК), который обеспечивает не только быструю генерацию документации, но и её непрерывное сопровождение — выявление устаревших комментариев, визуальную индикацию проблем и возможность обновления в один клик непосредственно из среды разработки.

Архитектура

ПМ АДПК реализован как расширение для интегрированной среды разработки Visual Studio Code. Выбор данной платформы обусловлен её популярностью среди C++ разработчиков, наличием развитого API для создания расширений и возможностью нативного выполнения кода на TypeScript в среде Node.js. Программа спроектирована по модульному принципу, что обеспечивает слабую связанность компонентов и упрощает тестирование.

Взаимодействие компонентов программного модуля представлено на рисунке 1.

Рис. 1. Схема взаимодействия компонентов программного модуля

Экстрактор элементов (ElementsExtractor) — центральный компонент синтаксического анализа. Он использует библиотеку web-tree-sitter [2] с загруженной WASM-грамматикой C++, что позволяет строить абстрактное синтаксическое дерево (AST) непосредственно в среде Node.js без внешних зависимостей. Экстрактор рекурсивно обходит AST и извлекает следующие сущности: функции, методы классов, классы и структуры, перечисления (enum), C++20 концепты. Для каждой сущности фиксируются имя, тело кода, расположение в документе (начальная и конечная позиции), метаданные (параметры с типами и значениями по умолчанию, возвращаемый тип, параметры шаблонов), а также связанный комментарий (если присутствует непосредственно перед объявлением).

Трекер изменений (ElementsChangeTracker) — компонент, отвечающий за мониторинг правок в редакторе. Он подписывается на события изменения текста документа и при каждом изменении проверяет, затронута ли область, содержащая документированную сущность (код функции/класса или сам комментарий). Для исключения частых проверок при интенсивном редактировании используется механизм отложенного анализа: при первом изменении запускается таймер (по умолчанию 60 секунд), который сбрасывается при каждом последующем изменении. Анализ выполняется только после истечения задержки, когда разработчик, вероятно, завершил редактирование.

Анализаторы качества документации — модули, оценивающие полноту и корректность комментариев. Поддерживаются два типа.

Smart-анализатор — выполняет локальную проверку без обращения к внешним API. Он анализирует наличие необходимых тегов JSDoc-подобного формата (@brief, @param, @return, @tparam), проверяет соответствие перечисленных параметров фактическим параметрам функции, оценивает полноту описания и вычисляет интегральную оценку качества от 0 до 100.

OpenRouter-анализатор — использует облачные большие языковые модели (через агрегатор OpenRouter [3]) для семантической оценки качества. Формирует запрос, содержащий код сущности и существующий комментарий, отправляет его к API и парсит JSON-ответ с оценкой и списком проблем.

Алгоритм работы

Алгоритм образует замкнутый цикл непрерывного сопровождения документации.

Инициализация — при активации расширения загружаются пользовательские настройки (выбор провайдера генерации, анализатора, задержка анализа, API-ключи), регистрируются слушатели событий и инициализируются подсистемы.

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

Мониторинг изменений — трекер отслеживает правки в редакторе. При изменении документированной сущности запускается отложенный анализ.

Анализ качества — после истечения задержки выбранный анализатор оценивает актуальность документации, формирует оценку и список проблем.

Визуализация — на основе результатов анализа обновляются цветовые индикаторы (зелёный/жёлтый/красный), всплывающие подсказки и боковая панель.

Генерация/обновление — по команде пользователя (через CodeLens, контекстное меню) менеджер документации вызывает соответствующий провайдер генерации, создаёт или обновляет комментарий, а интегратор вносит изменения в код.

Интерфейс

Пользовательский интерфейс реализован через стандартные механизмы расширения VS Code и включает следующие элементы:

CodeLens — интерактивные кнопки, отображаемые непосредственно над объявлением функции или класса. Для сущности без документации отображается кнопка «Generate», для сущности с существующей документацией — «Sync» (обновить) и «Remove» (удалить).

Визуальная подсветка — область комментария окрашивается в цвет, соответствующий оценке качества: зелёный (80–100 баллов) — документация актуальна; жёлтый (50–79) — имеются незначительные проблемы, рекомендуется доработка; красный (менее 50) — документация существенно устарела, требуется срочное обновление.

Hover-подсказка — при наведении курсора на подсвеченный комментарий появляется всплывающее окно с подробной информацией: оценка качества в процентах, количество проблем, детальный список несоответствий (например, «Не документирован параметр 'size'», «Отсутствует описание возвращаемого значения»), а также интерактивная кнопка «Fix Issues» для мгновенного обновления документации.

Боковая панель «Documentation Issues» — предоставляет сводную информацию по всем открытым файлам. Панель имеет иерархическую структуру (файлы → сущности с проблемами), для каждого элемента отображается тип, имя и оценка качества. При клике на сущность редактор автоматически переходит к соответствующей позиции в коде.

На рисунке 2 представлено изображение с интерфейсом программного модуля.

Рис. 2. Интерфейс программного модуля

Оценка эффективности

Для количественной оценки достижения заявленной цели проведено экспериментальное исследование с участием фокус-группы из пяти разработчиков, имеющих опыт промышленной разработки на C++. Каждому участнику предлагалось выполнить два идентичных задания по документированию программного кода.

Задание без модуля — вручную написать документацию в формате JSDoc для 10 функций, а затем после внесения трёх различных изменений в сигнатуры вручную же актуализировать комментарии.

Задание с модулем — выполнить те же операции с использованием ПМ АДПК (генерация через кнопку «Generate», обновление через кнопку «Sync»).

Фиксировалось чистое время, затраченное непосредственно на операции документирования (без учёта времени на написание самого кода).

Результаты показали, что применение ПМ АДПК обеспечивает сокращение временных затрат на операции документирования в среднем на 71,5 % по сравнению с ручным способом. Наибольший эффект достигается при актуализации документации после изменения сигнатур функций, когда модуль автоматически выявляет устаревшие комментарии и предлагает их обновление, тогда как при ручном подходе разработчик вынужден самостоятельно находить затронутые изменениями фрагменты и синхронизировать их с кодом.

Заключение

В ходе выполнения работы достигнута поставленная цель — разработан программный модуль ПМ АДПК для Visual Studio Code, решающий проблему поддержания документации в актуальном состоянии, которая не устраняется существующими аналогами

Разработанный модуль готов к интеграции в реальный процесс промышленной разработки на C++. Перспективы дальнейшего развития включают поддержку дополнительных языков программирования, а также разработку плагинов для других IDE.

Литература:

1. Silva L., Unterkalmsteiner M., Wnuk K. Towards identifying and minimizing customer-facing documentation debt // Proceedings of the 2023 ACM/IEEE International Conference on Technical Debt (TechDebt 2023). P. 72–81.
2. Родионов, И. Tree-sitter: обзор инкрементального парсера / И. Родионов. — Текст: электронный // Habr: [сайт]. — URL: https://habr.com/ru/articles/670140/ (дата обращения: 05.05.2026).
3. OpenRouter: единый API для доступа к LLM. — Текст: электронный // Habr: [сайт]. — URL: https://habr.com/ru/articles/943186/ (дата обращения: 04.05.2026).
4. Visual Studio Code официальная документация. — Текст: электронный // Visual Studio Code Extension API: [сайт]. — URL: https://code.visualstudio.com/api (дата обращения: 05.05.2026).