TL;DR
CodeDoc — способ писать описания функций и классов так, чтобы модель получала в промпте не весь репозиторий, а четыре блока в фиксированном порядке. Первым идёт список критериев качества, взятый из стандартов (ISO и гайд GitHub). Затем код целевой функции и её путь, код только прямых соседей (кто её вызывает и кого вызывает она) и инструкции по формату вывода. После первого ответа тот же список критериев отдаётся второй модели-судье. Судья ставит оценки по каждому критерию и пишет замечания, а модель переписывает текст с учётом замечаний.
Обычно либо кидают в модель весь репозиторий, либо просят «напиши docstring». В первом случае важные детали тонут в лишнем коде, а токены уходят впустую. Во втором модель сама решает, что считать «хорошей документацией». Выходит то подробно, то поверхностно, то без описания связей функции с остальным кодом. Критерии качества остаются в голове у модели, и проверить по ним нечем.
CodeDoc лечит это двумя ходами. Критерии пишутся явно и стоят в начале промпта. Контекст ограничен прямыми вызывающими и вызываемыми функциями. Затем та же рубрика проверяет результат и даёт один раунд доработки. В итоге качество по рубрикам выше, чем у RepoAgent (агентная система документирования репозиториев) и у подхода «весь код в контекст». Токенов уходит примерно на порядок меньше, чем у второго.
Схема метода
ПОДГОТОВКА (один раз): стандарты → список критериев (имя, определение, шкала 1–5)
ШАГ 1: найти для целевой функции прямых соседей
(кто вызывает / кого вызывает) → список сущностей
ШАГ 2: собрать промпт из 4 блоков в фиксированном порядке:
(1) критерии → (2) код цели + путь → (3) код соседей с пометками
uses / used_by → (4) инструкции формата вывода
→ черновик документации
ШАГ 3: судья проверяет черновик по тем же критериям
→ оценки по каждому критерию + текстовые замечания
ШАГ 4: к исходному промпту добавляются замечания → одна регенерация
→ финальная документация, привязанная к пути файла
Шаги 2 и 4 — один и тот же промпт с добавкой. Шаг 3 лучше делать отдельным запросом, чтобы судья не видел «хода мыслей» автора.
Пример применения
Задача: у вас Python-сервис для продавцов на Ozon и Wildberries. Функция calculate_payout() считает выплату: берёт комиссию маркетплейса, логистику и возвраты. Её вызывает build_monthly_report(), а сама она вызывает get_commission_rate(). Новый разработчик открывает функцию и не понимает, откуда берутся ставки и что будет, если ставка не найдена. Нужна нормальная документация.
Промпт:
## Критерии качества документации (учти каждый)
1. Корректность: описание соответствует тому, что код делает на самом деле.
2. Полнота: описаны назначение, параметры, возвращаемое значение, исключения.
3. Связи: указано, откуда функция получает данные и кто её использует.
4. Допущения: перечислены предусловия (формат входных данных, валюта, ожидания).
5. Читаемость: коротко, без воды, термины не меняются от абзаца к абзацу.
## Целевая сущность
Имя: calculate_payout
Путь: services/payouts/calc.py
Исходный код:
```python
[код calculate_payout]
Зависимости
uses: 1. services/rates/commission.py / get_commission_rate()
[код get_commission_rate]
used_by: 1. services/reports/monthly.py / build_monthly_report()
[код build_monthly_report]
Инструкции
Напиши docstring на русском для calculate_payout. Формат: краткое описание, Args, Returns, Raises, затем абзац «Связи» про uses / used_by. Не описывай то, чего нет в коде.
Второй запрос в новом чате (судья):
Ты проверяешь документацию к функции по 5 критериям (список ниже). Для каждого критерия поставь оценку 1–5 и одним предложением объясни, чего не хватает. Не переписывай текст. [критерии] [код цели и соседей] [черновик docstring]
Третий запрос — вернуться в исходный чат и вставить замечания судьи: «Перепиши docstring с учётом замечаний».
**Результат:** первым запросом придёт готовый docstring по заданному формату, включая блок про связи. Судья выдаст таблицу оценок по пяти критериям с короткими замечаниями. Например, что не сказано, как функция ведёт себя без ставки. После регенерации в тексте должны появиться недостающие допущения и исключения. Конкретных оценок и формулировок заранее не угадать.
## Почему это работает
**Слабость модели.** Если просить «напиши документацию», модель сама угадывает, что считать хорошим результатом. Каждый раз критерий немного другой, поэтому качество плавает. Если сунуть в промпт весь репозиторий, нужные детали **размываются** среди лишнего кода. Дорого и менее стабильно.
**Сильная сторона модели.** Модель хорошо следует явному списку требований и хорошо **сверяет текст с заданным критерием**. Проверять чужой черновик по рубрике ей проще, чем написать идеальный текст с первого раза.
**Как метод это использует.** Критерии в начале промпта задают планку. Прямые вызывающие и вызываемые функции дают ровно тот контекст, который объясняет роль функции. Одна и та же рубрика и в генерации, и в проверке означает, что **судья ищет именно то, чего просили от автора**. Замечания судьи превращаются в конкретные правки.
**Рычаги управления:**
- **Список критериев.** Уберите лишние для вашего проекта, добавьте свои («указать единицы измерения», «упомянуть побочные эффекты»). Это самый сильный рычаг.
- **Глубина зависимостей.** В исследовании берутся только прямые соседи. Для сложных связей можно добавить второй уровень, но токены вырастут.
- **Число раундов.** В исследовании использован один круг доработки. Для критичного кода можно два, для рутинного — ноль.
- **Судья.** Отдельный чат или другая модель убирают эффект «автор хвалит себя».
- **Инструкции вывода.** Формат (Google-style docstring, Markdown, Javadoc) подставляйте под свой проект.
## Шаблон промпта
Структура блоков и порядок — как в исследовании (критерии → цель → зависимости → инструкции). Сами пять критериев в шаблоне — пример. Полные рубрики (14 измерений по ISO и 12 по GitHub) есть в таблицах 7 и 8 статьи. В переданном тексте их нет, так что названия критериев ниже частично мои: они опираются на перечень тем, который приводят авторы.
Критерии качества документации
Каждый пункт: название — определение — как оценивать по шкале 1–5. {критерий_1} {критерий_2} {критерий_3} {критерий_4} {критерий_5}
Целевая сущность
Имя: {имя_функции_или_класса} Путь: {путь_к_файлу} Исходный код: ```{язык} {код_цели}
---
## Зависимости
uses (что вызывает цель):
1. {путь/имя_вызываемой}
```{язык}
{код_вызываемой}
used_by (кто вызывает цель): 1. {путь/имя_вызывающей} ```{язык} {код_вызывающей}
---
## Инструкции
Напиши {тип_документации} для целевой сущности на {язык_текста}.
Формат: {формат_вывода}.
Выполни все критерии выше. Описывай только то, что есть в коде.
Проверочный промпт (судья):
Ты — рецензент документации. Оцени текст по критериям ниже.
Для каждого критерия: оценка 1–5 и одно предложение, чего не хватает.
Текст не переписывай.
## Критерии
{те_же_критерии}
## Код цели и соседей
{код_цели_и_соседей}
## Документация на проверку
{черновик}
Что подставлять:
- {критерии} — список, который вы считаете признаком хорошей документации. Лучше взять из реального стандарта или гайда вашей команды.
- {код_вызывающей} / {код_вызываемой} — только прямые соседи. Найти их можно поиском по проекту или попросив об этом агента.
- {тип_документации} — docstring, описание класса, раздел справки.
🚀 Быстрый старт — вставь в чат:
Вот шаблон CodeDoc: рубрика критериев + код цели + прямые соседи + инструкции.
Адаптируй под мою задачу: [какую функцию или класс документирую, на каком языке, какой стиль нужен].
Задавай вопросы, чтобы заполнить поля.
[вставить шаблон выше]
LLM спросит про критерии качества, стиль документации и о том, какие функции вызывают вашу и какие вызывает она. Критерии и соседи — это два главных элемента метода, поэтому модели нужны ваши конкретные данные. Остальное она возьмёт из шаблона.
Ограничения
⚠️ Оценка идёт по той же рубрике, по которой писали: выигрыш измерен судьёй-LLM по критериям, которые стояли и в промпте. Это показывает, что текст соответствует рубрике, но не доказывает, что разработчикам стало понятнее. Корреляция судьи с людьми заметная, но не полная (Spearman ρ = 0,72).
⚠️ Одна модель и один язык: всё генерировалось и проверялось на одной и той же модели (GPT-5-mini) на десяти Python-репозиториях. На других моделях и языках результат придётся перепроверять.
⚠️ Зависимости строит скрипт: авторы извлекают связи автоматическим анализом кода (Pyan3 и разбор дерева кода). В чате список соседей придётся собирать руками или поручить агенту. Статический анализ вызовов может пропускать динамические вызовы.
⚠️ Только прямые соседи и один раунд доработки: сложные цепочки вызовов на несколько уровней метод не покрывает. Больше раундов авторы не проверяли (в предоставленном фрагменте).
⚠️ Масштаб: метод даёт документацию по одной сущности за раз. Для целого репозитория нужна автоматизация или агент, который пройдёт по файлам.
Как исследовали
Авторы сравнили CodeDoc на десяти открытых Python-репозиториях с двумя соперниками. Первый — RepoAgent, готовая система документирования репозиториев. Второй — «длинный контекст», когда в модель кладут много сырого кода. Всё (генерация и оценка) шло через GPT-5-mini. Рубрики вывели из стандарта ISO/IEC/IEEE (7 категорий, 14 измерений) и из гайда GitHub (5 категорий, 12 измерений). Сначала модель вытащила кандидатов из текстов стандартов, потом двое авторов вручную убрали дубли и привели формулировки к проверяемым. Каждое измерение получило имя, определение и шкалу 1–5.
По этим рубрикам CodeDoc оказался лучше RepoAgent на 11,6–17,0% и лучше длинного контекста на 21,4–29,6%. Токенов на одну сущность уходило примерно в десять раз меньше, чем у длинного контекста. Контекст из соседей работает лучше «всего подряд», потому что остаётся только нужное.
Чтобы проверить, что судья не фантазирует, авторы сравнили его оценки с человеческими и получили заметное, но не идеальное согласие (ρ = 0,72). Выводы сохранялись и при замене судьи на другие модели. Из текста понятно, что нет отдельного опыта «только критерии», «только соседи», «только судья», поэтому вклад каждого блока по отдельности не выделен. Проверен пакет целиком. Следовательно, практический вывод такой: пакет из рубрики в начале, ограниченного контекста и проверки той же рубрикой выигрывает у простого «напиши docstring». Какая часть даёт больше всего, из этого фрагмента не видно.
Адаптации и экстраполяции
🔧 Техника: судья в отдельном чате → меньше самоодобрения
Автор и судья в одном диалоге склонны подтверждать собственный текст. Откройте новый чат, вставьте только рубрику, код и черновик (без истории) и попросите «оценка 1–5 и одно предложение на критерий, текст не переписывать».
🔧 Техника: свои критерии вместо стандартных → документация под вашу команду
Если пишете для внутренней базы знаний, замените пять критериев на правила своей команды. Например: «указать единицы измерения», «указать, что будет при пустом входе», «ссылаться на тикет в Jira».
Экстраполяция: тот же принцип для инструкций агента. Задайте агенту (Claude Code, Cursor) в файле инструкций рубрику документации. Пусть он, прежде чем писать docstring, смотрит прямых вызывающих и вызываемых, а затем сам проверяет результат по этой рубрике:
Когда просят задокументировать функцию:
1. Найди её прямых вызывающих и вызываемых и прочитай только их.
2. Напиши docstring по критериям: корректность, полнота, связи, допущения, читаемость.
3. Перечитай результат как рецензент: оцени по каждому критерию 1–5.
4. Если есть оценка ниже 4, перепиши один раз и покажи итог.
Это моя адаптация, в исследовании так не проверялось.
Ресурсы
- Статья: Standards-Guided and Dependency-Aware Code-Level Documentation Generation (CodeDoc)
- Авторы: Tingxu Han, Wei Song, Ziming Li, Yuchen Chen, Weisong Sun, Zhenpeng Chen, Chunrong Fang, Zhenyu Chen, Yang Liu
- Организации: Nanjing University (State Key Laboratory for Novel Software Technology), UNSW Sydney, Nanyang Technological University, Tsinghua University
- Код: https://github.com/ControllableModel/CodeDoc
- Упомянутые стандарты: ISO/IEC/IEEE (документация ПО), GitHub documentation style guide
- Инструменты в статье: Pyan3 (граф вызовов), GPT-5-mini; сравнение с RepoAgent и RepoSummary