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

В кодовой базе оказалось 41 034 метода и 2 170 файлов. Если считать только основной код, без тестов, 12 093 метода из 19 880 были вообще без комментариев. Покрытие документацией получилось 39%.

Это не история про чужой легаси-проект. Это мой текущий код. Он просто рос быстрее, чем я успевал его объяснять.

На бумаге у меня всё было нормально: README, заметки по архитектуре, большой CLAUDE.md, отдельные пояснения по важным решениям. Но когда смотришь на реальные вопросы, которые возникают по ходу работы, быстро выясняется, что документация покрывает только часть из них.

Она неплохо отвечает на вопрос «зачем это сделано». Намного хуже с вопросами вроде:

кто вызывает эту функцию;
что сломается, если я поменяю вот этот класс;
как данные проходят от API до хранилища;
где в проекте самые рискованные и запутанные места.

Такие вещи живут не в текстах. Они живут в самом коде и в связях между его частями.

Почему документации тут мало

Новый разработчик открывает большой модуль и видит несколько тысяч строк, десятки вызовов наружу и сложность, в которую без подготовки лучше не лезть.

Его первый вопрос обычно не «какую бизнес-задачу решает этот проект». Это он ещё может прочитать в README.

Первый вопрос чаще другой: «Как эта штука вообще устроена и куда от неё тянутся хвосты?»

Если ответа нет под рукой, начинается стандартный путь: поиск по проекту, прыжки по импортам, ручной просмотр вызовов, догадки, вопросы в чат. Это занимает много времени и всё равно даёт картину кусками.

У меня долгое время работало именно так. Если нужно было быстро понять, что происходит, самым надёжным способом оставался вопрос ко мне. Это плохая схема. Один человек не должен быть единственным источником знаний о коде.

Что тут даёт граф кода

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

То есть не просто «вот файл и вот функция», а структура проекта в виде, по которому можно задавать вопросы.

Это не замена документации. Это ответ на другой класс задач.

Документация нужна, чтобы объяснить решения, ограничения, договорённости, общую модель системы.

Граф нужен, чтобы быстро ответить на структурные вопросы:

кто вызывает функцию;
что затронет изменение;
как связаны модули;
где самые сложные места;
есть ли вообще у метода реальные вызовы.

Эти вещи неудобно поддерживать руками. Они меняются слишком быстро.

Четыре вопроса, которые действительно помогают в работе

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

Первый: «Кто вызывает эту функцию?»

Обычный поиск по имени даёт кучу шума: импорты, тесты, похожие названия, комментарии. Чтобы понять, используется ли функция по-настоящему, всё равно приходится вручную разбирать результаты.

Если смотреть через граф, можно сразу получить список реальных вызывающих мест и контекст. Не просто «встречается в таких-то файлах», а «вызывается в таких-то сценариях и участвует вот в этом потоке».

Второй: «Что затронет моё изменение?»

Это особенно полезно перед рефакторингом. Например, если меняется базовая структура данных, хочется заранее увидеть не только прямые зависимости, но и места, где она сериализуется, уходит в API или протаскивается через несколько слоёв.

Ручной поиск такое часто пропускает. Особенно если связь неочевидная.

Третий: «Как устроен этот модуль?»

Есть файлы, которые просто трудно читать линейно. Они большие, с кучей ветвлений, внутренних шагов и внешних зависимостей. В таких случаях полезно сначала получить сжатую структурную картину: точки входа, основные части, внешние зависимости, важные методы, примерный радиус связей.

Это не заменяет чтение кода, но сильно сокращает время на вход.

Четвёртый: «Где горячие точки?»

Если в проекте сотни файлов и тысячи методов, бессмысленно чинить всё подряд. Нужен короткий список мест, где одновременно высокая сложность, слабое покрытие тестами и много связей с остальным кодом.

Так хотя бы понятно, куда смотреть в первую очередь.

Что граф заменяет, а что нет

Тут полезно не переоценивать инструмент.

Граф не объяснит, зачем вы выбрали одну архитектуру вместо другой. Не расскажет о продуктовых ограничениях. Не заменит ADR, вики и нормальные проектные заметки.

Но он отлично закрывает то, что обычно не успевает попасть в документацию:

фактические вызовы;
зависимости между частями системы;
радиус изменения;
сложные и рискованные точки;
мёртвый код;
циклы между модулями.

Это важное различие.

Вопрос «почему мы храним это в DuckDB, а не в PostgreSQL?» — это документация.

Вопрос «кто вызывает _collect_metrics и что ещё заденет его изменение?» — это уже задача для графа.

Что показал самоаудит

Когда я собрал всё это на своём же проекте, цифры получились такие:

41 034 метода;
2 170 файлов;
покрытие документацией — 39%;
максимальная цикломатическая сложность — 133;
753 метода со сложностью выше 10 и без тестов;
495 методов длиннее 100 строк;
268 комментариев TODO и FIXME;
2 циклические зависимости между модулями.

Это не катастрофа, но и не повод делать вид, что всё под контролем.

Хорошая сторона в том, что после такого аудита хотя бы понятно, что делать дальше. Не в абстрактном смысле «надо улучшать качество», а вполне по списку: вот тяжёлые методы, вот файлы-монолиты, вот код без тестов, вот места с лишней связанностью.

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

Вывод у меня довольно простой.

Документация всё ещё нужна. Без неё никуда. Но она не решает задачу навигации по живому проекту целиком. Особенно если проект быстро меняется.

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

Иначе получается знакомая схема: код меняется каждый день, документы устаревают, а отвечать на вопросы всё равно идёт один и тот же человек.

Если коротко, граф кода полезен не потому, что он «умный». Он полезен потому, что снимает с человека ту часть работы, которую бессмысленно делать вручную снова и снова.

Когда код растёт быстрее документации