Практика применения PlantUML для анализа и документирования кода

17.04.26

Разработка - Рефакторинг и качество кода

+4 –
> >
  • Пример диаграммы последовательности.jpg
  • Прецеденты использования.jpg
  • Пример диаграммы классов.jpg
Как быстро разобраться в чужом коде? Как не забыть через полгода алгоритм работы своего собственного кода? Как наглядно проектировать? Ответам на эти вопросы посвящена данная публикация.

1. Проблематика

Можно выделить несколько направлений для использования PlantUML:

  • Анализ чужого кода;
  • Обратная разработка (reverse engineering) собственного кода при:
    • Его возрастающей сложности;
    • Возвращении к собственному коду спустя продолжительное время после написания (фактор забывания);
  • Наглядное проектирование;

 

2. Методика

В качестве методики анализа и документирования выбраны UML диаграммы:

  • Прецедентов использования (use case diagram). Позволяют увидеть функциональные требования к системе.
  • Классов (class diagram). Позволяют увидеть структуру метаданных и API.
  • Последовательности (sequence diagram). Позволяют отследить цепочки вызовов операций кода.

 

3. Структура

Представим документацию набором html-страниц с UML-диаграммами.

3.1. Главная страница

Главную (стартовую) страницу документации назовём "Описание прикладного решения".

Её структура:

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

Пример:

 

 

  • Функциональные возможности. Расширенное описание функциональных возможностей, покрывающих прецеденты использования.
  • UI. Содержит внешний вид ключевых форм
  • Версия платформы 1С, на которой работает прикладное решение.

3.2. Страница прецедента использования

Содержит реализацию одного функционального требования.

Структура страницы:

  • Проектное решение
    • Структура метаданных и API. Реализуется UML диаграммой классов (class diagram).

Пример:

 

 

  • Последовательность вызова кода. Реализуется UML диаграммой последовательности (sequence diagram).

Пример:

 

 

  • Руководство пользователя. Содержит описание реализации прецедента с точки зрения пользовательской функциональности.

 

4. Резюме

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

 

5. Инструментарий

Практику применения PlantUML для анализа и документирования кода автоматизирует мой проект "Чеширский кот: База знаний из Зазеркалья". Выгрузка .dt файла базы данных проекта содержит много примеров PlantUML диаграмм с исходным кодом, используемым для самодокументирования "Чеширского кота".

Вступайте в нашу телеграмм-группу Инфостарт

база знаний markdown памятка справка PlantUML UML чеширский кот нейросеть GigaChat wiki говорящая вики DeepWiki документация зазеркалье ИИ AI вики блокнот заметки ТЗ

+4 –

Вы можете заказать платную адаптацию этой статьи под ваши задачи на «Бирже заказов».

  • 0% комиссии — оплата напрямую исполнителю;
  • Исполнители любого масштаба — от отдельных специалистов до команд под проект;
  • Прямой обмен контактами между заказчиком и исполнителем;
  • Безопасная сделка — при необходимости;
  • Рейтинги, кейсы и прозрачная система откликов.

См. также

Аудитор кода 1С

Инструментарий разработчика Рефакторинг и качество кода Программист 1С 8.3 1С 8.5 1С:Документооборот 1С:Бухгалтерия 3.0 1С:Управление нашей фирмой 3.0 Россия Абонемент ($m)

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

2 стартмани

08.07.2026    530    5    NikolayMaerov    0    

4
С 659 до 43 часов: как мы ускорили установку обновления «1С:ERP» 2.4 на 2.5

Рефакторинг и качество кода Обновление 1С Программист 1С:Предприятие 8 1С:ERP Управление предприятием 2 Бесплатно (free)

На проекте сложного обновления 1С:ERP 2.4.14.181 до версии 2.5.22.106 нам было нужно уложить обновление в технологическое окно 48 часов (выходные). Исходный замер, с учетом промежуточных релизов 2.5.8.443, 2.5.12.270, 2.5.17.234, 2.5.22.106, показал требуемое время в 659 часов…

07.07.2026    3293    1c-izh    20    

21
«Чистые» доработки: как обновить доработанную роль в поставляемом расширении 1С

Рефакторинг и качество кода Обновление 1С Программист 1С 8.3 Бесплатно (free)

Обновление ролей в расширении 1С отличается от аналогичного процесса в основной конфигурации. Ситуация осложняется, когда доработки вносятся не в «обычное», а в поставляемое расширение.

26.06.2026    1197    1c-izh    3    

5
Code review в 1С без токсичности

Рефакторинг и качество кода Программист Россия Бесплатно (free)

Code review в 1С часто превращается в спор вкусов: “мне не нравится”, “переделай”, “так не делают”. В статье разбираю другой подход: проверять не разработчика, а риск для системы. Показываю, как формулировать замечания без токсичности, где заканчивается личное предпочтение и начинается реальная проблема, почему ревью должно развивать разработчика, а не только исправлять код

24.06.2026    939    NikolayMaerov    4    

6
Код-ревью 1C с ИИ: как собрать рабочего ассистента на RAG без Git, Sonar и EDT

Нейросети Рефакторинг и качество кода Программист Бесплатно (free)

Показываем, как встроить ИИ-помощника в code review 1С без Git, SonarQube и EDT – только с Конфигуратором, RAG-контекстом и набором MCP-инструментов. Разбираем архитектуру решения на Open Web UI и OpenRouter, методику сравнения моделей по Precision, Recall, BonusRate и PenaltyRate, а также объясняем, почему контекст влияет на качество ревью сильнее, чем выбор самой модели. На реальных примерах показываем, какие ошибки ИИ находит хорошо, где все еще нужен архитектор и почему на старте пилота время ревью может не сократиться, а вырасти. В финале делимся метриками внедрения и выводами для команд, которые хотят повторить такой подход у себя.

17.06.2026    1252    NVyunova    1    

3
Code-review с помощью искусственного интеллекта. Не все так просто

Нейросети Рефакторинг и качество кода Программист Бесплатно (free)

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

09.06.2026    2221    Repich    5    

9
Почему команда начинает бояться собственного кода

Рефакторинг и качество кода Программист Бесплатно (free)

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

04.06.2026    1184    IgorVasilyev    29    

5
MetaVision PRO: разбор модулей, графы функций, аудит безопасности и новые фишки PRO-версии

Инструментарий разработчика Рефакторинг и качество кода Программист 1С 8.3 Абонемент ($m)

MetaVision for 1C PRO — профессиональная версия статического анализатора и визуализатора кода. Загружает выгрузки конфигураций, расширения и внешние файлы, за секунды строит графы функций, находит уязвимости безопасности и подсвечивает проблемы производительности. В арсенале: визуализация логики в виде графов условий, циклов, транзакций и вызовов, статический аудит безопасности с поиском RCE, SSRF, COM-инъекций и паролей в коде, выявление запросов в циклах и вложенных блокировок, полнотекстовый поиск по всем модулям, встроенный редактор с конвертером запросов и автоформатированием, а также честная статистика по объектам и функциям. Главное новшество PRO — до пяти конфигураций одновременно с мгновенным переключением, наложение до пяти расширений как в конфигураторе, анализ внешних файлов в единой связке с основной конфигурацией и пять тем оформления. Инструмент для тех, кто ведёт несколько проектов параллельно и хочет видеть полную картину в одном окне — быстро, наглядно и безопасно.

7 стартмани

19.05.2026    3480    36    KHoroshulinAV    7    

13
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. ksnik 702 17.04.26 09:20 Сейчас в теме
Автор в заголовке написал - для анализа и документирования кода. Выразил свой опыт. Но получился отрывок потому, что код начинается не с реверс инжениринга.

Бизнес-требования (зачем этот код вообще нужен)

Архитектурные решения (как код вписывается в систему)

Модели данных (с чем код работает)

Процессы (как код взаимодействует с внешним миром)

У автора есть 3 типа диаграмм (Use Case, Class, Sequence) и набор HTML-страниц. А что дальше? Как это вписать в архитектуру предприятия? Как не плодить хаос из разных нотаций? Как сделать так, чтобы документация не устарела?

Вместо введения. Коротко о главном, чего не хватает в исходной статье:

1. «Диаграммы как код» — это да, но нужна экосистема
PlantUML хорош, но один он не решает проблему устаревания документации. Нужна связка:

Git (хранение .puml файлов рядом с кодом)

CI/CD (автоматическая генерация PNG/SVG) - генератор https://plant-uml-editor.vercel.app/ и валидатор Plantuml Validation MCP Server

Confluence (единое хранилище, Single Source of Truth)

Это называется Living Documentation. Тогда диаграммы всегда соответствуют реальности. А не просто «я нарисовал HTML-страничку и выложил».

2. UML — не единственная нотация, и не всегда лучшая
Автор хвалит UML. Но для разных задач — разные инструменты. Вот полная карта

— Для показа системы целиком заказчику:
Нотация: C4 (уровень Context)
Когда использовать: вместо громоздких Use Case диаграмм

— Для описания структуры крупных модулей (БД, бэкенд, фронт):
Нотация: C4 (Containers/Components)
Когда использовать: легковесная альтернатива UML Component

— Для детального проектирования классов и API:
Нотация: UML Class Diagram (PlantUML)
Когда использовать: да, тут автор прав

— Для показа цепочки вызовов во времени:
Нотация: UML Sequence Diagram (PlantUML)
Когда использовать: сильная сторона PlantUML

— Для проектирования базы данных:
Нотация: ER-диаграмма (PlantUML тоже умеет)
Когда использовать: в статье забыли про данные

— Для описания бизнес-процесса под автоматизацию:
Нотация: BPMN 2.0
Когда использовать: золотой стандарт, исполнимые модели

— Для стратегического анализа функций компании:
Нотация: IDEF0
Когда использовать: когда важна иерархия, а не последовательность шагов

— Для описания архитектуры предприятия в целом (бизнес → приложения → технологии):
Нотация: ArchiMate + TOGAF
Когда использовать: для масштаба холдинга, а не одного модуля

3. PlantUML с C4 — это 4 уровня приближения:

Уровень 1 (Context) — система и внешние пользователи (можно заменить Use Case)

Уровень 2 (Containers) — веб-приложение, БД, мобилка

Уровень 3 (Components) — модули внутри контейнера

Уровень 4 (Code) — здесь и нужен PlantUML (Class, Sequence, Activity)

То есть PlantUML — это инструмент для самого нижнего, детального уровня. Пытаться нарисовать им всю архитектуру — как микроскопом забивать гвозди.

4. А где всё это хранить и кто отвечает?
Автор предлагает набор HTML-страниц. Это архаика. В современной практике:

Хранилище — Confluence (пространства → страницы → вложения)

Структуру настраивает Администратор Confluence

За актуальность по своему продукту отвечает Product Owner

Стандарты моделирования утверждает Архитектурный комитет или BPM Center of Excellence

Диаграммы перерисовываются автоматически через CI/CD (никто не забывает руками обновлять)

Итог: не «или», а «и»

Исходная статья про PlantUML — это хороший частный случай. Но если вы хотите внедрить моделирование на уровне компании, нужна система:

TOGAF — как процесс (что делать и в каком порядке)

ArchiMate — как язык для связки бизнеса и IT

C4 Model — для быстрого документирования архитектуры ПО (понятно всем)

BPMN 2.0 — для бизнес-процессов, которые пойдут в автоматизацию

PlantUML — для «диаграмм как код» на детальном уровне (классы, последовательности, ER)

Confluence + Git + CI/CD — для хранения и актуализации

Тогда у вас будет целостная картина, а не вырванный из контекста UML.
HiddenPilot; Cmapnep; SirAlex; chuprina_as; +4 – Ответить
2. chuprina_as 294 17.04.26 09:48 Сейчас в теме
(1) Спасибо за развёрнутый ответ описания проблематики. Записал себе в план развития прикладного решения «Чеширский кот».

Но один нюанс я всё-таки отмечу. То, что вы привели, это очень трудозатратно, это большая экосистема, а хотелось бы что-то, что разворачивается вот сразу из коробки. Это HTML-странички. Понятно, что в разговоре об автоматизации возникает много функциональных недостатков такого подхода.

Я рассчитываю, что со временем в "Чеширском коте" я их разрешу, но главное всё-таки иметь под рукой удобный, нетрудозатратный инструмент, разворачиваемый из коробки. А то, что вы привели... Я не знаю бюджет проекта, на котором это окупится.

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

Ещё раз спасибо за развёрнутый ответ. Я обязательно воспользуюсь идеями, предложенными вами. Но с поправкой, что это должно быть наглядно, просто и понятно, даже если проектная команда состоит из всего лишь одного программиста. Чтобы он мог с минимальными трудозатратами выполнять функции анализа и документирования.
+ – Ответить
3. ksnik 702 17.04.26 10:52 Сейчас в теме
(2) я предложил вместо введения, можно нарисовать на бумажке-сфоткать или в пайнте, вложить картинку.
+ – Ответить
4. chuprina_as 294 27.04.26 08:44 Сейчас в теме
(1) Здравствуйте! Постепенно обрабатываю замечания из вашего комментария выше для повышения качества инструментария. Ещё раз спасибо за развёрнутые пожелания. Вы не зря уделили время их написанию.

За отправную точку я взял проблему устаревания документации в момент написания и предложенную вами концепцию "диаграммы как код - Living Documentation":

1. «Диаграммы как код» — это да, но нужна экосистема
PlantUML хорош, но один он не решает проблему устаревания документации. Нужна связка:

Git (хранение .puml файлов рядом с кодом)

CI/CD (автоматическая генерация PNG/SVG) - генератор https://plant-uml-editor.vercel.app/ и валидатор Plantuml Validation MCP Server

Confluence (единое хранилище, Single Source of Truth)

Это называется Living Documentation. Тогда диаграммы всегда соответствуют реальности. А не просто «я нарисовал HTML-страничку и выложил».


Мой подход к реализации Living Documentation:

* Документацию пишет нейросеть по заданному промпту. Мне удалось получить качественный (на мой взгляд) результат. Подробнее в статье: https://infostart.ru/1c/articles/2677969/

* В качестве инструмента документирования и интеграции с нейросетью я использую свой проект "Чеширский кот: База знаний из Зазеркалья": https://infostart.ru/1c/tools/2664571/ Сейчас хочу самодокументировать его авто-документацией, полученной от нейросети, попутно допилив сам проект на основе полученного опыта.

На этом моя обработка вашего комментария продолжится. Буду держать в курсе.
VyacheslavShilov; +1 – Ответить
Для отправки сообщения требуется регистрация/авторизация