Практика применения 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 Абонемент ($m)

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

10 стартмани

02.11.2026    374    2    nedomolkov.ivan    3    

3
Где проверять обязательный параметр в 1С: в обработчике команды или перед запросом?

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

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

29.10.2026    385    YA_777378709    0    

4
Рефакторинг – не роскошь: как внедрить культуру улучшений в команде

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

Рассказываем, почему качественный код – это не техническая прихоть, а актив, который помогает бизнесу быстрее адаптироваться к изменениям и запускать новые фичи без бесконечного преодоления техдолга. Показываем, как объяснить бизнесу ценность рефакторинга через понятные признаки: замедление разработки, неточные оценки, страх перед legacy и хрупкость системы. Разбираем, почему неправильный рефакторинг может быть дороже его отсутствия, какие анти-паттерны ломают процесс и как не превратить улучшения в бесконечную переделку ради переделки. Объясняем, как сделать рефакторинг частью культуры команды: договориться с бизнесом, научить разработчиков видеть проблемные места, закрепить правила и поддерживать улучшения на уровне тимлидов, архитекторов и всей команды.

28.10.2026    500    Pavel791    0    

2
Нагрузка на HTTP-сервис 1С: опытная проверка скриптом

Рефакторинг и качество кода HighLoad оптимизация Системный администратор Разработчик Стажер 1С 8.3 Абонемент ($m)

Если к HTTP-сервису 1С обращаются сразу несколько программ, сколько запросов в секунду он успеет обработать? Я опубликовала простой HTTP-сервис на нашей "подопытной" конфигурации «Нано-УТ» (файловая база, Apache, без прав администратора) и нагрузила его скриптом на Python. Ответ: около 15-16 запросов в секунду, сколько бы клиентов ни обращалось одновременно. Запросы ждут своей очереди, и при 32 клиентах ответ приходит через 2 секунды вместо 64 мс. Заодно разобрала скрипт из первого варианта статьи: он «проверял» сервер, который отвечал по одному, и считал ошибки вместе с успешными ответами. В архиве исправленный скрипт, учебный сервер, HTTP-сервис для 1С и инструкция по запуску.

1 стартмани

23.10.2026    530    Ninel_S    3    

2
Перегруженные модули 1С: Analyzer 1C и разнесение модуля

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

Запустили Analyzer 1C 2.7.65 на промышленной конфигурации (596 модулей, 13 669 функций) и исследовали перегруженные функции (до 1887 строк), циклические зависимости и экран «Циклы» (кольцо из 64 модулей). Разобрали, почему популярные метрики (McCabe, связность) не представлены в продукте вендора, и составили пошаговый план разделения модуля. Привели проверенный платформой 8.3.27 пример до и после рефакторинга и выявили скрытую ловушку загрузки модулей с точкой в имени.

9 стартмани

19.10.2026    469    Ninel_S    2    

2
Грабли СКД, невидимые в конструкторе

Рефакторинг и качество кода EDT СКД Разработчик 1С 8.3 1С 8.5 1С:Бухгалтерия 3.0 Бесплатно (free)

Одиннадцать граблей схем компоновки, которые не видно в конструкторе и не ловит EDT, на реальных отчетах БП КОРП. Формат числа задается в двух местах, и условное оформление варианта перебивает формат поля. Ресурс складывает штуки с часами, и помогает выражение «только когда единица одна». Ресурс пуст в детальных записях, параметр не появляется в шапке без userSettingID, valueListAllowed ломает границы периода, Остатки и СрезПоследних с параметром периода падают с «Несоответствием типов», title без xsi:type дает «Исключение XDTO» при загрузке. В конце код проверки схемы из файла до обновления базы, сводная таблица и чеклист.

16.10.2026    550    Konstmax13    2    

2
ИИ-агент в EDT: 40 правил

Инструментарий разработчика Нейросети Рефакторинг и качество кода EDT Разработчик 1С 8.3 1С 8.5 1С:Бухгалтерия 3.0 Бесплатно (free)

Как ИИ-агент (Claude Code) работает в живом EDT-проекте 1С:Бухгалтерии КОРП 3.0: из чего собрать стенд с MCP-сервером для EDT, как ставить задачи агенту, где он ломает проект и какие проверки это ловят. Реальные случаи: рукописные метаданные, ронявшие конфигуратор; четыре дня зависшего обновления из-за порядка блоков в Rights.rights; ошибки, которые EDT пропускает, а платформа нет; сплошная сверка вместо «вроде работает». В приложении шаблон CLAUDE.md, шаблон правила, чеклист перед обновлением базы и скрипты проверки ролей и схем СКД.

15.10.2026    3517    Konstmax13    11    

11
Способ транзитивного анализ вызовов в платформе 1С:Предприятие

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

Инженерный анализ влияния (Impact Analysis) при изменении общего метода в 1С:Предприятии: почему штатный поиск ссылок скрывает 99% зависимостей и как обратный обход графа вызовов выявляет 370 скрытых потребителей на глубине 3 уровней. В статье — верификация сквозной цепочки обмена с маркетплейсом; в архиве-компаньоне — автономный BFS-анализатор на Python, слепки графа и план регрессионного тестирования.

1 стартмани

12.10.2026    335    Ninel_S    0    

2
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. ksnik 728 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 728 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 – Ответить
Для отправки сообщения требуется регистрация/авторизация