Einführung
Ich bin Systemanalytiker und habe die Aufgabe, automatisierte Informationssysteme zu entwerfen. Nein, es geht jedoch darum, Dokumente zu schreiben und zu schreiben. Das dritte Mal werde ich das Wort "schreiben" nicht wiederholen - schließlich nicht die "Ilias". Aber die langweilige Form von etwas macht die Projektdokumentation definitiv eng mit dem antiken griechischen Gedicht verbunden, insbesondere wenn es um die Zusammenarbeit mit dem Staatskunden geht.
Diagramme sind ein Schluck Kreativität in diesem Meer von Texten. Diagramme werden in diesem Artikel behandelt. Genauer gesagt - über PlantUML - aus meiner Sicht das derzeit am besten geeignete Werkzeug, um sie zu erstellen.
Ich bin sicher, dass viele von PlantUML gehört haben, zumindest hat es auf GitHub mehr als tausend Sterne . Die Bedeutung dieses Tools ist äußerst einfach. Sie können nur Diagramme (größtenteils in UML-Notation) in Form von Text angeben, der die Elemente und die Beziehungen zwischen ihnen beschreibt. Eine grafische Ansicht wird automatisch erstellt. Das Folgende ist ein Beispiel für ein Aktivitätsdiagramm.
start : ; if (?) then () : ; if (?) then () else () : ; endif : ////; else () stop endif stop
Trotz der Popularität gibt es nur sehr wenige Artikel über Habré, die über die praktische Anwendung dieses Tools sprechen. Es scheint mir, dass PlantUML einen solchen Mangel an Aufmerksamkeit nicht verdient.
Am Anfang werde ich Ihnen erklären, warum ich es als Hauptwerkzeug für die visuelle Modellierung ausgewählt habe, und am Ende werde ich eine Reihe von Empfehlungen geben, die ich selbst gerne hören würde, als ich anfing, dieses Werkzeug zu verwenden.
Warum PlantUML
Aus meiner Sicht ist es beim Erstellen von Diagrammen sinnvoll, sich auf die folgenden Kriterien zu konzentrieren: (1) Das Diagramm sollte weniger oder weniger klein sein, (2) das Diagramm sollte mehr oder weniger Standardnotation verwenden und (3) das Diagramm sollte unter dem Gesichtspunkt der Verwaltung der Projektdokumentation weniger oder weniger praktisch sein .
In allen drei Fällen wurde das Wort „weniger“ verwendet, da alle diese Kriterien in bestimmten Situationen unbeschadet des Falls verletzt werden können. Es gibt viele große Diagramme, die in selbst erstellter Notation erstellt und zur Perfektion gebracht wurden (dieselbe U-Bahn-Karte ). Eine andere Frage ist, dass die Erstellung solcher Diagramme Projekte sind, die ernsthafte Ressourcen aufgewendet haben. Weit davon entfernt, immer (gelesen, nie) solche Ressourcen für die Erstellung automatisierter Informationssysteme bereitzustellen. Der Kunde braucht ein perfektes System, kein perfektes Systemdiagramm.
Für mich sind diese Kriterien jedoch der Ausgangspunkt, von dem aus Sie ein Diagramm erstellen. Weiter ... wie es geht.
Lange Zeit betrachtete ich die Verwendung von Microsoft Visio als einen goldenen Schnitt für mich und zeichnete dort Diagramme, um UML einigermaßen nahe zu kommen. In diesem Fall wurde ein Standardsatz von Komponenten verwendet, da dieser mehr Freiheit bietet als eine spezielle Schablone für UML. Außerdem wurden einige Diagramme zur Anzeige auf dem Projektor in Microsoft PowerPoint gezeichnet.
Ja, Sie können solche Diagramme nicht verwalten. Wenn sich der Name einer Entität geändert hat, öffnen Sie jedes Diagramm und ändern Sie es. Aber es fällt fast schön aus. Und es gibt eine gewisse Flexibilität bei der Formulierung von Gedanken.
Ich habe auch spezielle Geschäftsmodellierungswerkzeuge ausprobiert: Rational Rose, Aris, Enterpise Architect (Sparx Systems), vor allem Rational Rose. Das Problem ist, dass das Endergebnis meiner Arbeit Dokumente sind. In diesem Sinne müssen Sie das gesamte Projekt manuell durchgehen und die Diagramme an den richtigen Stellen des Textes wieder einfügen, wenn sich die Anforderungen ernsthaft ändern. Etwas auszudenken, vielleicht in diesem Teil zu automatisieren, schien mir zu kompliziert und die Mühe nicht wert.
Mit dem Aufkommen von PlantUML hat sich die Situation radikal geändert.
Sobald die Diagramme in Form von Text erstellt wurden, bedeutet dies, dass Sie in jedem Texteditor (ich mag Atom und Notepad ++) den erforderlichen Text in einer Reihe von Dateien finden und sogar ersetzen können. Projekt-Refactoring ist sehr praktisch. Das Textformat erleichtert außerdem das Organisieren von Gruppenarbeiten und das Verfolgen von Änderungen im Versionskontrollsystem.
In PlantUML ist das Erstellen von Diagrammen schneller als in jedem visuellen Editor (zumindest für mich). Es gibt andere Meinungen zu diesem Thema, zum Beispiel, dass das Erstellen eines Diagramms in PlantUML länger ist als beispielsweise in Enterpise Architect (Sparx Systems). Ich denke, das ist eher eine Frage des Geschmacks und der Gewohnheit.
Ich hatte sogar ziemlich erfolgreiche Erfahrungen, als PlantUML anstelle eines Boards verwendet wurde (es war nicht in der Nähe) und mit Leuten, die sehr weit von der Informationstechnologie entfernt waren.
PlantUML ist flexibel genug, um die UML-Notation zu verwenden. Es unterstützt alle seine Grundelemente und bietet dem Benutzer viele Möglichkeiten für die kostenlose Verwendung im Diagramm. Zum Beispiel ist es sehr praktisch, die Verwendung von Wiki-Markups im Inhalt von Elementen zu unterstützen.
Darüber hinaus sehen die Entwickler von PlantUML anscheinend nichts Falsches daran, die Notation zu brechen. Und das ist ein großer Vorteil dieses Tools. Letztendlich muss der Client nicht wissen, ob UML UML ist oder nicht - er muss die Bedeutung des Diagramms verstehen. Alles, was zu einer Verbesserung der Sinneswahrnehmung führt, ist gut.
Trotzdem ist PlantUML UML, d.h. Die allgemein anerkannte Notation, der Standard und damit die Dokumentation, insbesondere in Regierungsprojekten, ist sehr gut geeignet.
Mit PlantUML können Sie keine großen Diagramme erstellen. Er verteilt die Elemente selbst und natürlich beginnt das Ergebnis bei einer großen Anzahl von Elementen zweifelhaft zu sein. Dies ist jedoch keine Einschränkung. Wenn PlantUML anfängt, ein unzureichendes Ergebnis zu erzielen, stellen Sie normalerweise fest, dass PlantUML nicht schlecht ist, das Diagramm jedoch schlecht. Es ist besser, es zu trennen oder die Anzahl irrelevanter Details zu verringern.
PlantUML-Diagramme können automatisch generiert werden. Ein Beispiel für eine solche Verwendung finden Sie hier .
Wir verwenden PlantUML, um automatisch ein Datenbankschema zu generieren. Die Funktion einer solchen Generierung ist in das von uns verwendete Datenbankstruktur-Management-Tool 2bass integriert . Daher ist beim Zusammenstellen der Dokumentation das Klassendiagramm mit der Datenbankstruktur immer auf dem neuesten Stand. Die folgende Abbildung zeigt einen Teil der Beschreibung der Datenbankstruktur und ein automatisch generiertes Diagramm.
PlantUML Tipps
Es scheint mir, dass viele PlantUML nicht verwenden, weil sie im Anfangsstadium auf bestimmte Schwierigkeiten stoßen, die sie für grundlegend unüberwindbar halten. Viele haben Angst vor der Verwendung von Text, weil jeder an Grafikeditoren gewöhnt ist. Dieser Teil des Artikels enthält Empfehlungen, die es Ihnen hoffentlich ermöglichen, PlantUML schnell in Kampfmissionen einzusetzen.
Wo werden Diagramme erstellt?
Zunächst möchte ich PlantUML Web Server erwähnen, einen Teil des PlantUML-Projekts, in dem Sie Diagramme online erstellen und mit Kollegen teilen können. Dies ist eine sehr praktische Funktion, aber natürlich nicht beim Erstellen von Diagrammen für die Projektdokumentation.
Oft wird PlantUML in Wiki-Engines verwendet. Hier erfolgt die Bearbeitung auf übliche Weise: Text wird geschrieben, gespeichert und auf der Seite erhalten wir ein Bild. In den meisten Fällen ist es jedoch zweckmäßig, dass das Ergebnis sofort im Diagramm angezeigt wird: Beispielsweise wird die Spezifikation des Diagramms im linken Fenster geschrieben und das Erscheinungsbild im rechten Fenster angezeigt. Der fertige Text kann bereits in das Wiki eingefügt werden.
Die PlantUML-Website hat viele Redakteure. Ich vermute, dass mehr als die Hälfte von ihnen nicht für die Arbeit geeignet sind. Am liebsten erstelle ich PlantUML-Diagramme mit dem PlantUML Preview- Plug-In im Atom-Editor. In der Tat gibt es mehrere solcher Plugins. PlantUML Preview hat mir insofern gefallen, als es nicht nur das Ergebnis anzeigt, sondern sofort (oder zum Zeitpunkt des Speicherns - abhängig von den Einstellungen) eine Grafikdatei erstellt, deren Name der Datei mit der Spezifikation des Diagramms entspricht.
Das heißt, Jedes Diagramm entspricht immer zwei Dateien, einer Textdatei (mit einer Textbeschreibung des Diagramms) und der anderen Grafik (ein Bild mit einem Diagramm).
Da wir die gesamte Dokumentation schon lange mit Hilfe von Asciidoctor erstellt haben (es ist erstaunlich, wie die Ablehnung von Microsoft Word es einfacher machen kann, aber dies ist das Thema eines separaten Artikels), fügen wir die Bilder über die Links ein. Um das Bild mit dieser Technologie zu ändern, öffnen Sie einfach die Textbeschreibung, ändern Sie sie und speichern Sie sie. Sie müssen keine Export- oder Kopiervorgänge über die Zwischenablage ausführen.
Bitte beachten Sie, dass für das PlantUML Preview-Plug-In in seinen Einstellungen der Speicherort der Datei planuml.jar angegeben werden muss. PlantUML selbst funktioniert nicht, wenn GraphViz nicht installiert ist. Beide Anwendungen können von den entsprechenden Sites heruntergeladen werden. In den neuesten Versionen von PlantUML wird Graphviz auslaufen, sodass dieses Produkt in naher Zukunft autonomer wird. Dies vereinfacht die Verwendung in Systemen zur automatischen Zusammenstellung der Programmdokumentation.
Diagramme zum Drucken vorbereiten
Für einen qualitativ hochwertigen Druck auf einem Laserdrucker müssen Sie den Parameter skinparam dpi 300 angeben. Die Auflösung von 300 dpi bietet ein qualitativ hochwertiges Bild zum Drucken auf einem Laserdrucker. Andernfalls werden Bilder mit Bildschirmauflösung erstellt und sehen gerastert aus. PlantUML kann auch svg (Vektorformat) verwenden. Dieses Format wird jedoch viel weniger unterstützt als PNG, und es gibt viel mehr Probleme damit. Ich habe svg verwendet, wenn es notwendig war, das Bild mit einem Vektoreditor ein wenig in Erinnerung zu rufen (z. B. mit Inkscape ). Dies ist natürlich ein äußerst seltener Anwendungsfall für PlantUML.
Um Schatten zu entfernen, die normalerweise auch das gedruckte Erscheinungsbild beeinträchtigen, wird der Parameter skinparam shadowing false verwendet.
Außerdem ist es zum Drucken eines Diagramms auf einem Schwarzweißdrucker wünschenswert, dass es keine Halbtöne aufweist. Ein Farbschema mit Braun und Gelb ist normalerweise nicht zum Drucken geeignet. Glücklicherweise können Sie mit PlantUML die verwendeten Farben angeben. Die folgenden Optionen zeigen beispielsweise ein Komponentendiagramm in einer Schwarzweißpalette an. Es gibt einen speziellen Parameter für die Erzeugung von Schwarzweißdiagrammen ( Skinparam Monochrom True ), der jedoch nur die Farbe entfernt, Halbtöne bleiben erhalten.
skinparam component { borderColor black backgroundColor white ArrowColor black }
Eine Liste der meisten Parameter finden Sie hier . Wenn Sie alle Parameter untersuchen möchten, können Sie den Befehl java -jar plantuml.jar -language verwenden .
Relative Anordnung der Elemente
Der Richtungsparameter von links nach rechts bewirkt, dass die Diagrammelemente von links nach rechts gezeichnet werden. Nicht sehr offensichtlich, aber zum Beispiel für ein Komponentendiagramm bedeutet dies, dass die Komponenten auf der linken Seite und die Schnittstellen auf der rechten Seite zusammengesetzt werden.
component " 1" as c1 component " 2" as c2 interface " 1" as i1 c1
Gruppierung mit übergeordneten Elementen.
In der folgenden Abbildung hat PlantUML die Komponenten so verteilt, dass weniger Linienschnittpunkte vorhanden sind. Diese Reihenfolge der Komponenten kann unerwünscht sein, wenn die Komponenten der Reihe nach angezeigt werden sollen.
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
Wenn wir die zweite und dritte Komponente gruppieren, erreichen wir, dass die Komponenten in der richtigen Reihenfolge angeordnet sind.
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
Die Reihenfolge der Komponenten. Ein eher kontroverser Ansatz, der aber funktioniert. Im folgenden Beispiel wird Komponente 2 zuerst als angezeigt In der Spezifikation wird es zuerst aufgeführt.
component " 2" as c2 component " 1" as c1 interface " 1" as i1 c1
PlantUML kann auch Pfeilrichtungen anzeigen. Um beispielsweise anzuzeigen, dass der Pfeil von links nach rechts von Komponente 1 (c1) zu Schnittstelle 1 (i1) wechselt, müssen Sie in der Pfeilspezifikation den Buchstaben „r“ angeben: c1 -r- () i1 . Das folgende Beispiel zeigt deutlich, dass der Pfeil von Komponente 1 zu Schnittstelle 1 von links nach rechts und von Komponente zwei zu derselben Schnittstelle von rechts nach links verläuft.
component " 1" as c1 component " 2" as c2 interface " 1" as i1 c1 -r-() i1 c2 -l-( i1
Ich denke, das ist eine schädliche Gelegenheit. Es verwirrt die Spezifikation des Diagramms und PlantUMLs Interpretation der Richtung kann ziemlich exotisch sein. Wenn Sie den Parameter für die Richtung von links nach rechts angeben, bedeutet der Buchstabe „r“ außerdem von oben nach unten (aufgrund der Verschiebung im Uhrzeigersinn), was das Schema vollständig verwirrt.
Beschriften Sie Elemente
Mehrzeiliger Text und Wiki-Markup
PlantUML bietet einige gute Werkzeuge zum Formatieren von Text in Elementen.
Beim Generieren eines Diagrammelements basiert PlantUML auf der Größe des Texts. Das heißt, Nicht der Text fließt abhängig von der Größe des Elements, sondern die Größe des Elements passt sich dem Text an.
Der einfachste Weg, großen Text zu erstellen, ist die Verwendung des Zeichens \ n. In diesem Fall können Sie auch Textformatierungszeichen (fett, kursiv usw.) verwenden.
component "** 1** \n \n //****// \n* //// 1 \n* // 2//" as c1
Manchmal gibt es keine anderen Optionen. In den meisten Fällen wird jedoch eine Syntax unterstützt, mit der Sie mehrzeiligen Text angeben können. Im vorherigen Beispiel können Sie diese Syntax beispielsweise verwenden.
component c1 [ ** 1** ==== ..//****//.. * //// 1 * // 2// ] note left .... ** 1** ==== ..//****//.. * //// 1 * // 2// end note
Wie wir sehen können, können mit dieser Syntax Trennlinien hinzugefügt werden. Beachten Sie, dass hier eine Notiz hinzugefügt wird, die denselben Text wie die Komponente anzeigt. Gleichzeitig wird in der Notiz die Liste als Liste und in der Komponente als Text durch das Symbol „*“ angezeigt. Leider funktionieren Listen und Tabellen in Komponenten nicht. Obwohl sie beispielsweise in Elementen arbeiten, die Aktivität darstellen (im Aktivitätsdiagramm).
Verwenden von Symbolen
PlantUML unterstützt verschiedene Möglichkeiten zur Verwendung von Symbolen. Alle von ihnen haben bestimmte Einschränkungen.
Am beliebtesten ist meines Erachtens die Technologie der Verwendung sogenannter Sprites. Ein Sprite ist eine Bitmap, die mithilfe von Text festgelegt wird. Das größte Plus dieser Technologie ist, dass Sie mit PlantUML externe Sprite-Bibliotheken erstellen können. Es gibt mehrere solcher Bibliotheken. Was mir am besten gefällt, ist die PlantUML Icon-Font Sprites- Bibliothek, weil Es enthält grafische Bilder von Font Awesome .
Beachten Sie, dass Sprites in PlantUML Bitmaps sind, d. H. Sie haben Einschränkungen bei der Skalierung. In dieser speziellen Bibliothek beträgt die Auflösung der Symbole 48 x 48 Pixel. Wenn ein solches Bild zum Drucken verwendet wird, ist es unerwünscht, es auf eine Größe von mehr als 5 Millimetern zu skalieren (was ungefähr einer Auflösung von 250 dpi entspricht). Bei vielen Internetquellen, die die Verwendung von Sprites beschreiben, wird dies nicht berücksichtigt, und die Beispiele zeigen Diagrammelemente mit großen Symbolen. Auf dem Bildschirm sehen diese Diagramme gut aus, aber wenn sie gedruckt werden, sehen sie gerastert aus.
Die Größe des Symbols von 4 bis 5 Millimetern kann bequem in den Signaturen verwendet werden. In der folgenden Abbildung werden beispielsweise mithilfe der Symbole Benutzerrollen angezeigt, deren Mitglieder den Prozess von einem Status in einen anderen übertragen.
' !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{_CS}> !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>
Einige Symbole sind direkt in PlantUML integriert, ich bevorzuge jedoch die Verwendung externer Bibliotheken. Insbesondere sind die Symbole aus diesem Beispiel in der Awesome v5-Bibliothek enthalten, und zum Zeitpunkt des Schreibens des aktuellen Artikels (Version 1.2018.08) ist nur die Awesome v4-Bibliothek in PlantUML integriert.
Anführungszeichen verwenden
Diese scheinbar einfache Frage hat mich fast daran gehindert, PlantUML zu verwenden. Das Fehlen von Zitaten sieht unprofessionell und lustig aus.
PlantUML unterstützt viele Möglichkeiten, Anführungszeichen zu verwenden. Aber als Ergebnis der Suche fand ich nur einen, der immer funktioniert, guten alten Schrott: zum Öffnen russischer Anführungszeichen - <U + 00AB>, zum Schließen von Anführungszeichen - <U + 00BB>, für universelle Anführungszeichen - <U + 0022>.
So verlieren Sie sich nicht im Diagramm
Die Syntax im Aktivitätsdiagramm ist so praktisch, dass es schwierig ist, sich zu verwirren, weil Es ist eher eine Beschreibung eines Algorithmus als eine Beschreibung eines Diagramms. Aber hier in anderen Diagrammen: Zustände, Komponenten, Bereitstellung, Anwendungsfälle, Klassen und andere ist es ziemlich leicht, verwirrt zu werden.
Zwei einfache Regeln helfen mir, nicht verwirrt zu werden.
Geben Sie alle Elemente über Schlüsselwörter ein (verwenden Sie keine vereinfachte Syntax). Wenn das Element dies zulässt, legen Sie einen Alias dafür fest.
Geben Sie die Beziehung unmittelbar nach dem Element an (natürlich, wenn das zugehörige Element bereits im Diagramm vorhanden ist). Tatsache ist, dass ein Element im Text immer leicht zu finden ist. Eine Verbindung kann nur durch Alias gefunden werden. Wenn Sie diese Regel verwenden, kann die Verbindung auch schnell im Text gefunden werden.
Fazit
PlantUML ist kein Spielzeug. Dies ist ein hochwertiges, universelles Tool, mit dem Sie fast alle Probleme lösen können, die mit der Beschreibung von Geschäftsprozessen und Architekturmerkmalen der entworfenen Systeme verbunden sind.
PlantUML hat eine psychologische Eintrittsbarriere: Wir sind zu sehr an visuelle Editoren gewöhnt und die Verwendung von Text scheint ein Rückschritt zu sein. Aber wenn sich herausstellt, dass sich dank dieses Rückschritts die Effizienz ihrer Arbeit erhöht, warum nicht?
PlantUML weist Lücken in der Implementierung auf: Einige Funktionen funktionieren nur für einen Teil von Diagrammen oder grafischen Grundelementen. In der Praxis können solche Einschränkungen jedoch immer umgangen werden. PlantUML ist ein ausgereiftes und stabil funktionierendes Produkt, auf das Sie sich bei Ihrer Arbeit voll und ganz verlassen können, ohne befürchten zu müssen, dass es das Diagramm ruiniert oder die Schriftart verzerrt oder ein anderes Problem beseitigt, das zu einer schlaflosen Nacht führt, bevor die nächste Phase des Projekts abgeschlossen wird.