Практика применения 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 Бесплатно (free)

Есть запросы, которые сразу вызывают подозрение: десятки соединений, множество временных таблиц, объединения, группировки и длинный список условий. Но чаще проблемы прячутся в другом месте — в запросах, которые выглядят вполне приемлемо. Пара обращений через точку, отбор после виртуальной таблицы, РАЗЛИЧНЫЕ «чтобы убрать дубли», большой список в параметре, реквизит регистратора через составной тип — и вот уже на тестовой базе все летает, а в рабочей базе отчет открывается минуту. Разберу такие случаи из практики: не синтаксические ошибки, а именно запросы, которые формально нормальные, но на больших данных начинают вести себя плохо.

04.05.2026    736    YA_2060655612    11    

8
Токсичный рефакторинг: когда хорошие намерения приводят к проблемам

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

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

29.04.2026    545    _apelsin4ik    0    

5
Почему код в 1С сначала работает быстро, а потом внезапно начинает тормозить?

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

Код в 1С редко начинает тормозить сразу. Намного чаще он долго выглядит нормальным, а проблемы проявляются позже — когда растут данные, пользователи и количество доработок. В статье разбираю типичные причины такой деградации: запросы в цикле, лишние ПолучитьОбъект(), тяжёлые формы и обработку “по одному”. Статья практическая: с примерами, типичными ошибками и понятными признаками того, что код уже плохо масштабируется.

21.04.2026    1578    YA_2060655612    6    

11
Твой 1С-код под колпаком: сканер уязвимостей, транзакций, «мертвых» переменных и многого другого

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

Инструмент для тех, кто устал читать модули по 50 тысяч строк и искать ошибки глазами. MetaVision загружает выгруженные файлы конфигурации и за секунды строит графы функций, находит уязвимости и подсвечивает проблемы производительности. Ключевые возможности: Визуализация логики функций (графы условий, циклов, транзакций и вызовов). Статический аудит безопасности (RCE, SSRF, COM-инъекции, пароли в коде). Поиск проблем производительности (запросы в циклах, вложенные блокировки). Полнотекстовый поиск по всем модулям конфигурации. Статистика по объектам и функциям. Безопасность: Программа работает строго локально. Код вашей конфигурации не отправляется в интернет и не анализируется на сторонних серверах. Попробуйте MetaVision сегодня — узнайте, что скрывает ваш код.

20.04.2026    8231    821    KHoroshulinAV    51    

69
ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Программа "Chunk Advisor" (Консультант по чанкам)

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

Создадим скрипт на Пайтон, предназначенный для автоматизированного подбора чанков (фрагментов требований к коду) при разработке на 1С. Она помогает разработчику формировать качественные промпты для ИИ, включающие все необходимые требования безопасности, производительности и стандартов кодирования. Кому интересно, покритикуйте и предложите улучшения. Результаты опубликуем.

20.03.2026    1294    ksnik    4    

5
Когда ИИ выставит счёт?

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

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

17.03.2026    1859    IgorVasilyev    54    

27
История одной оптимизации, давшей тысячекратный прирост производительности!

Рефакторинг и качество кода Программист 1С:Предприятие 8 1С:Комплексная автоматизация 2.х 1C:ERP Бесплатно (free)

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

09.02.2026    1956    Eugen-S    10    

5
Вайб-кодинг в 1С: Как заставить ИИ писать новый код с помощью MCP-серверов

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

В статье рассказываю, как писать код 1С в VS Code с помощью бесплатных AI-моделей 🤖 Используем GLM-4.7 через Roocode + Cerebras (до 1 миллион токенов в день). Подключаем бесплатные MCP. Генерируем новый код и смотрим, как AI справляется с задачами.

06.02.2026    16853    Ibrogim    83    

52
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. ksnik 688 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 273 17.04.26 09:48 Сейчас в теме
(1) Спасибо за развёрнутый ответ описания проблематики. Записал себе в план развития прикладного решения «Чеширский кот».

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

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

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

Ещё раз спасибо за развёрнутый ответ. Я обязательно воспользуюсь идеями, предложенными вами. Но с поправкой, что это должно быть наглядно, просто и понятно, даже если проектная команда состоит из всего лишь одного программиста. Чтобы он мог с минимальными трудозатратами выполнять функции анализа и документирования.
+ – Ответить
3. ksnik 688 17.04.26 10:52 Сейчас в теме
(2) я предложил вместо введения, можно нарисовать на бумажке-сфоткать или в пайнте, вложить картинку.
+ – Ответить
4. chuprina_as 273 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 – Ответить
Для отправки сообщения требуется регистрация/авторизация