Главная » Хабрахабр » PlantUML — все, что нужно бизнес-аналитику для создания диаграмм в программной документации

PlantUML — все, что нужно бизнес-аналитику для создания диаграмм в программной документации

Введение

Впрочем, нет, она заключается в том, чтобы писать и писать документы. Я — системный аналитик, и моя работа заключается в том, чтобы проектировать автоматизированные информационные системы. Но занудность формы чем-то определенно роднит проектную документацию с древнегреческой поэмой, особенно если речь идет о работе с государственным заказчиком. Третий раз слово «писать» повторять не буду — все-таки, не «Илиада».

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

Смысл этого инструмента исключительно прост, он всего лишь позволяет задавать диаграммы (по большей части в нотации UML) в виде текста, описывающего элементы и связи между ними. Уверен, многие слышали о PlantUML, по крайней пере, на GitHub у него стоит больше тысячи звезд. Далее приведен пример диаграммы деятельности. Графический вид создается автоматически.

start
:Вывалить мысли
в текст;
if (Бред?) then (Возможно) :Дать посмотреть коллеге; if (Сойдет?) then (Да) else (Нет) :Помедитировать над текстом; endif :Разместить на //Хабре//;
else (Точно) stop
endif
stop

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

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

Почему PlantUML

С моей точки зрения при создании диаграмм имеет смысл ориентироваться на следующие критерии: (1) диаграмма должна быть более менее небольшой, (2) диаграмма должна использовать более менее стандартную нотацию и (3) диаграмма должна быть более менее удобной с точки зрения управления проектной документацией.

Есть много больших диаграмм, созданных в самодельной нотации и доведенных до совершенства (та же карта метрополитена). Во всех трех случаях использовалось слово «более менее», потому что все эти критерии в конкретных ситуациях можно нарушать без ущерба для дела. Далеко не всегда (читай, никогда) такие ресурсы выделяются на создание автоматизированных информационных систем. Другой вопрос, что создание таких диаграмм — проекты, на которые потрачены серьезные ресурсы. Заказчику нужна совершенная система, а не совершенная диаграмма системы.

Дальше…​ как сложится. Тем не менее для меня эти критерии являются точкой отсчета, от которого начинаешь придумывать диаграмму.

При этом использовался стандартный набор компонентов, поскольку он дает больше свободы, чем специализированный stencil для UML. Очень долгое время золотым сечением для себя я считал использование Microsoft Visio и рисовал там диаграммы, стараясь быть разумно близким к UML. Также некоторые диаграммы для показа на проекторе рисовались в Microsoft PowerPoint.

Если поменялось название какой-либо сущности, открываем каждую диаграмму и меняем ее. Да, управлять такими диаграммами нельзя. И есть определенная гибкость в формулировании мысли. Зато получается почти красиво.

Проблема в том, что конечный результат моей работы — это документы. Также пробовал специализированные инструменты бизнес-моделирования: Rational Rose, Aris, Enterpise Architect (Sparx Systems), — в наибольшей степени Rational Rose. Что-то придумывать, возможно, автоматизировать в этой части мне показалось слишком сложным и не стоящим усилий. И в этом смысле, если что-то серьезное меняется в требованиях, все равно необходимо вручную проходить по всем проекту и заново вставлять диаграммы в нужные места текста.

С появлением PlantUML ситуация в корне изменилась.

  1. Рефакторинг проекта вполне удобен. Раз диаграммы создаются в виде текста, значит в любом текстовом редакторе (мне нравятся Atom и Notepad++) можно найти требуемый текст в наборе файлов и даже заменить его. Также текстовый формат дает возможность легко организовывать групповую работу и осуществлять отслеживание изменений в системе контроля версий.

  2. На этот счет есть и другие мнения, например, здесь говорится, что создание диаграммы в PlantUML дольше, чем, скажем в Enterpise Architect (Sparx Systems). В PlantUML создавать диаграммы быстрее, чем в любых визуальных редакторах (по крайней мере, для меня). Думаю, это скорее вопрос вкуса и привычки.

    У меня был даже вполне успешный опыт, когда PlantUML использовался вместо доски (не было ее рядом), причем с людьми, весьма далекими от информационных технологий.

  3. Поддерживая все основные ее элементы, он дает пользователю множество возможностей для их свободного использования в диаграмме. PlantUML достаточно гибко подходит к нотации UML. Например, очень удобной является поддержка использования вики-разметки в содержимом элементов.

    И это большое достоинство данного инструмента. Более того, разработчки PlantUML, видимо, ничего плохого в нарушении нотации не видят. Все, что ведет к улучшению восприятия смысла, хорошо. В конечном счете, клиент не должен знать, UML это или не UML — он должен понимать смысл диаграммы.

    общепринятая нотация, стандарт, а значит для документации, особенно в государственных проектах, очень подходит. И тем не менее PlantUML — это UML, т.е.

  4. Он распределяет элементы самостоятельно и, естественно, при большом количестве элементов результат начинает быть сомнительным. PlantUML не позволяет создавать больших диаграмм. Обычно, когда PlantUML начинает выдавать неадекватный результат, понимаешь, что не PlantUML плохой, а диаграмма плохая, и лучше ее разделить или уменьшить количество несущественных деталей. Но это не совсем ограничение.

  5. Пример такого использования приведен в здесь. Диаграммы PlantUML можно генерировать автоматически.

    Функция такой генерации встроена в используемый нами инструмент управления структурой баз данных  — 2bass. Мы используем PlantUML для автоматической генерации схемы базы данных. На следующем рисунке показан кусок описания структуры базы данных и автоматически созданная диаграмма. Таким образом, при сборке документации диаграмма классов со структурой БД находится всегда в актуальном состоянии.

Советы по использованию PlantUML

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

Где создавать диаграммы?

Это очень удобная возможность, но, конечно же, не при создании диаграмм для проектной документации. Для начала хотелось бы упомянуть PlantUML Web Server — часть проекта PlantUML, на котором диаграммы можно создавать онлайн и делиться ими с коллегами.

Здесь редактирование происходит стандартным образом: пишется текст, сохраняется, и на странице мы получаем картинку. Часто PlantUML используется в вики-движках. Готовый текст уже можно вставить в wiki. Но все-таки, в большинстве случаев удобно, чтобы на диаграмме сразу отображался результат: например, в левом окне пишется спецификация диаграммы, в правом — отображается ее внешний вид.

Подозреваю, что среди них больше половины не пригодны для работы. На сайте PlantUML приведено много редакторов. На самом деле таких plugin'ов несколько. Мне больше всего нравится создавать PlantUML-диаграммы с помощью plug-in'а PlantUML Preview в редакторе Atom. PlantUML Preview мне понравился тем, что он не только показывает результат, но сразу (или в момент сохранения — в зависимости от настроек) создает графический файл, имя которого соответствует файлу со спецификацией диаграммы.

каждой диаграмме всегда соответствует два файла, один текстовый (с текстовым описанием диаграммы), а другой — графический (картинка с диаграммой).
Т.е.

Для изменения картинки при такой технологии работы достаточно открыть текстовое описание, изменить его и сохранить. Поскольку мы всю документацию давно делаем с помощью Asciidoctor (удивительно, насколько отказ от Microsoft Word может облегчить работу, но это тема отдельной статьи), то картинки вставляем через ссылки. Делать операции экспорта или копирования через буфер обмена при этом не нужно.

В последних версиях PlantUML идет последовательный отказ от использования Graphviz, поэтому в ближайшее время данный продукт станет более автономным. Обратите внимание, что plug-in PlantUML Preview в своих настройках требует указания местонахождения файла planuml.jar, а сам PlantUML не будет работать, если не установлен GraphViz, оба приложения можно скачать с соответствующих сайтов. Это упростит его использование в системах автоматической сборки программной документации.

Подготовка диаграмм для печати

Разрешение в 300 dpi обеспечивает качественный рисунок для печати на лазерном принтере. Для качественной печати на лазерном принтере необходимо указать параметр skinparam dpi 300. В PlantUML есть также возможность использовать svg (векторный формат). В противном случае картинки создаются с экранным разрешением и выглядят растрированными. Я использовал svg, если необходимо было немного довести картинку до ума векторным редактором (например, с использованием Inkscape). Но данный формат поддерживается гораздо меньше, чем png, и проблем с ним гораздо больше. Но это, конечно же, крайне редкий вариант использования PlantUML.

Для убирания теней, которые обычно тоже портят печатный вид, используется параметр skinparam shadowing false.

Цветовая схема, использующая коричневые и желтые цвета, для печати обычно не подходит. Кроме того, для печати диаграммы на черно-белом принтере желательно, чтобы она не имела полутонов. Следующие параметры, например, обеспечивают отображение диаграммы компонентов в черно-белой палитре. К счастью PlantUML позволяет задавать используемые цвета. Существует специальный параметр для монохромной генерации диаграммы (skinparam monochrome true), но он только убирает цвет, полутона остаются.

skinparam component { borderColor black backgroundColor white ArrowColor black
}

Если хочется изучить все параметры, можно воспользоваться командой java -jar plantuml.jar -language. Перечень большинства параметров приведен здесь.

Относительное расположение элементов

  1. Не очень очевидно, но, например, для диаграммы компонентов это означает, что компоненты будут собраны в левой части, а интерфейсы — в правой. Параметр left to right direction делает так, чтобы элементы диаграммы отрисовывались слева направо.

    component "Компонент 1" as c1
    component "Компонент 2" as c2
    interface "Интерфейс 1" as i1
    c1 --() i1
    c2 --( i1

  2. Группировка с помощью элементов более высокого уровня.

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

    component "Компонент 1" as c1
    component "Компонент 2" as c2
    component "Компонент 3" as c3
    interface "Интерфейс 1" as i1
    c1 --() i1
    c2 --( i1
    interface "Интерфейс 2" as i2
    c1 --() i2
    c3 --( i2

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

    component "Компонент 1" as c1
    component "Модуль 1" {
    component "Компонент 2" as c2
    component "Компонент 3" as c3
    }
    interface "Интерфейс 1" as i1
    c1 --() i1
    c2 --( i1
    interface "Интерфейс 2" as i2
    c1 --() i2
    c3 --( i2

  3. Довольно спорный подход, но работает. Порядок задания компонентов. в спецификации он указан первым. В следующем примере на рисунке сначала отображается Компонент 2, т.к.

    component "Компонент 2" as c2
    component "Компонент 1" as c1
    interface "Интерфейс 1" as i1
    c1 --() i1
    c2 --( i1

Например, чтобы указать, что стрелка идет из компонента 1 (c1) в интерфейс 1 (i1) слева направо, необходимо в спецификации стрелки указать букву «r»: c1 -r-() i1. В PlantUML есть еще возможность указывать направления стрелки. В следующем примере явно указано, что стрелка из компонента 1 в интерфейс 1 идет слева направо, а из компонента два в этот же интерфейс справа налево.

component "Компонент 1" as c1
component "Компонент 2" as c2
interface "Интерфейс 1" as i1
c1 -r-() i1
c2 -l-( i1

Она запутывает спецификацию диаграммы и особенность интерпретации направления PlantUML'ем может быть весьма экзотичной. Мне кажется, это вредная возможность. Кроме того, при указании параметра left to right direction буква «r» начинает означать сверху вниз (из-за смещения по часовой стрелке), что совсем уж запутывает схему.

Надписи в элементах диаграммы

Многострочный текст и wiki-разметка

PlantUML содержит неплохие средства для форматирования текста в элементах.

Т.е. При генерации элемента диаграммы PlantUML исходит из размера текста. не текст перетекает в зависимости от размера элемента, а размер элемента подстраивается под текст.

В этом случае можно также использовать символы форматирования текста (жирный, курсив и т.п.) Самый простой вариант создания большого текста — использование символа «\n».

component "**Компонент 1** \n Не входит ни в один пакет \n //**Экспонирует**// \n* //Интерфейс// 1 \n* //Интерфейс 2//" as c1

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

component c1 [ **Компонент 1** ==== Не входит ни в один пакет ..//**Экспонирует**//.. * //Интерфейс// 1 * //Интерфейс 2//
] note left Тот же текст в примечании .... **Компонент 1** ==== Не входит ни в один пакет ..//**Экспонирует**//.. * //Интерфейс// 1 * //Интерфейс 2//
end note

Обратите внимание, здесь добавлено примечание, отображающее тот же текст, что и компонент. Как мы видим, при использовании такого синтаксиса появляется возможность добавлять разделительные линии. К сожалению, в компонентах списки и таблицы не работают. При этом в примечании список отображается, как список, а в компоненте, как текст через символ «*». Хотя они, например, работают в элементах, отображающих деятельность (в диаграмме деятельности).

Использование иконок

Все они обладают определенными ограничениями. PlantUML поддерживает несколько способов использования иконок.

Спрайт — это растровый рисунок, который задается при помощи текста. Наиболее востребованной, как мне кажется, стала технология использования так называемых спрайтов. Таких библиотек несколько. Самый большой плюс этой технологии заключается в том, что PlantUML позволяет создавать внешние библиотеки спрайтов. она содержит графические изображения из Font Awesome. Мне больше всего нравится библиотека PlantUML Icon-Font Sprites, т.к.

у них есть ограничения по масштабированию. Обратите внимание, что спрайты в PlantUML являются растровыми изображениями, т.е. При использовании такого изображения для печати нежелательно масштабировать его до размеров более 5 миллиметров (что примерно соответствует разрешению 250 dpi). В данной конкретной библиотеке разрешение иконок составляет 48 на 48 точек. На экране такие диаграммы смотрятся отлично, но при печати выглядят растрированными. На многих интернет-ресурсах, описывающих использование спрайтов, это не учитывается и в примерах приводятся элементы диаграмм с крупными иконками.

Например, на следующем рисунке с помощью иконок показаны пользовательские роли, члены которых осуществляют перевод процесса из одного состояния в другое. Размер иконки в 4-5 миллиметров удобно использовать внутри подписей.

' Импорт иконок и создание удобных алиасов
!define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.0.0
!includeurl ICONURL/common.puml
!includeurl ICONURL/font-awesome-5/user_cog.puml
!includeurl ICONURL/font-awesome-5/user_check.puml
!define _CS scale=0.4
!define _user_cog <$user_cog>
!define _user_check <$user_check{_CS}> 'Легенда
legend ..**Условные обозначения**.. _user_cog — Сотрудник _user_check — Контролёр
endlegend 'Спецификация диаграммы состояний
state "Документ формируется" as prepare_doc
[*] --> prepare_doc state "Документ на проверке" as check_doc
prepare_doc --> check_doc : _user_cog \n Передать \nна проверку
check_doc --> prepare_doc : _user_check \n Отправить \nна доработку state "Документ проверен" as ready_doc
check_doc --> ready_doc: _user_check \n Установить отметку \n<U+00AB>Проверено<U+00BB>

В частности, иконки из данного примера содержатся в библиотеке Awesome v5, а в PlantUML на момент написания текущей статьи (версия 1. Некоторые иконки встроены непосредственно в PlantUML, однако мне больше нравится использовать внешние библиотеки. 08) встроена только библиотека Awesome v4. 2018.

Использование кавычек

Отсутствие кавычек выглядит непрофессионально и смешно. Этот на первый взгляд простой вопрос оказался для меня чуть ли не блокирующим в использовании PlantUML.

Но в результате поисков я нашел только один, который работает всегда, старый добрый лом: для открывающих русских кавычек — <U+00AB>, для закрывающих — <U+00BB>, для универсальных — <U+0022>. PlantUML поддерживает много способов использования кавычек.

Как не запутаться в диаграмме

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

Мне помогают не запутаться два простых правила.

  1. Если элемент позволяет, задавать для него алиас. Вводите все элементы через ключевые слова (не использовать упрощенный синтаксис).

  2. Дело в том, что элемент всегда легко найти по тексту. Указывайте связь непосредственно за элементом (разумеется, если связанный элемент уже присутствует на диаграмме). Если же пользоваться данным правилом, то связь можно также быстро найти по тексту. А связь можно найти только по алиасу.

Заключение

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

  2. Но если благодаря этому шагу назад получается повысить эффективность своей работы, почему его не сделать? У PlantUML есть психологический барьер входа: мы слишком привыкли к визуальным редакторам и использование текста кажется шагом назад.

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


Оставить комментарий

Ваш email нигде не будет показан
Обязательные для заполнения поля помечены *

*

x

Ещё Hi-Tech Интересное!

HighLoad++ Awards: награда, которую деплоили, деплоили и наконец задеплоили

Например, придумали механику asset pipeline на Rails, и в 2011–2012 году о ней начали выходить статьи в американских блогах, о ней раструбили по всему миру. — На рынке очень грустная ситуация в отношении того, насколько мы, программисты, умеем делиться знаниями ...

Youtube-party: История компьютерных игр

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