Практика применения 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 –

См. также

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

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

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

20.03.2026    976    ksnik    4    

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

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

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

17.03.2026    1647    IgorVasilyev    51    

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

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

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

09.02.2026    1736    Eugen-S    10    

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

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

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

06.02.2026    14696    Ibrogim    80    

50
Вайб-кодинг в 1С: как рефакторить код бесплатно с помощью VS Code и Roo Code

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

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

02.02.2026    13068    Ibrogim    54    

49
Делай как надо, а как не надо - не делай. Личный ТОП-10 ошибок в коде 1С, от которых дергаться глаз

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

Открываешь код и глаз начинает дёргается? Я собрал личный список ТОП-10 самых раздражающих и опасных ошибок в 1С, с примерами, юмором и практическими рекомендациями, как писать так, чтобы потом не было мучительно больно.

31.01.2026    3738    GarriSoft    89    

6
Как я выбираю: костыль, рефакторинг или чистая архитектура. Мой алгоритм, выверенный многолетней практикой

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

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

19.12.2025    2658    GarriSoft    14    

17
История о том, как Вася Пупкин спас квартальный отчет Марьи Ивановны

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

История о легендарном отчете на 11 000 строк, копеечном расхождении и костыле 2014 года, который пережил все обновления. О том, как Василий спас квартальное закрытие, не тронув ни единой строчки кода монолита

15.12.2025    1969    GarriSoft    21    

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

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

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

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

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