Diagramy jako kod – na przykładzie PlantUML

Nawet jeżeli nie zajmujesz się programowaniem, to nie zamykaj tego artykułu. Tu nie będzie o kodowaniu w C# czy Javie. Będzie o tym, dlaczego diagramy jako kod pomagają zaoszczędzić czas i nerwy.

Wyzwania w rysowaniu diagramów

Narzędzi do modelowania wymagań jest wiele (zobacz ten artykuł). Większość z nich ma te same problemy, czyli:

Niekontrolowane przesuwanie elementów

Dodajesz jeden element, a coś innego się przesuwa. Chcesz to cofnąć, ale diagram rozjeżdża się w innym miejscu. Wykonujesz niewinne połączenie dwóch elementów, które jednak rozpycha wszystko dookoła, powodując wielki chaos.

Tak się nie da modelować!

Zamiast skupiać się na merytoryce, walczysz z narzędziem.

Ciężko wprowadzić zmianę

Załóżmy, że udało się zbudować model. Ustawiłeś elementy tak, że nic już się nie rozjeżdża. Niestety, po kilku dniach wymagania się zmieniają i trzeba nanieść poprawki.

Cała przygoda zaczyna się od nowa. Chcesz podmienić tylko jeden element, ale po usunięciu go strzałki zaczynają wariować. Rozjeżdżają się po diagramie, zmieniając model w losowy sposób.

Pozostaje się modlić, żeby nie było więcej zmian…

Kosztowne licencje

Większość dobrych narzędzi wymaga wykupienia licencji. Przez to albo wzrastają koszty utrzymywania takiej dokumentacji, albo wydłuża się czas, kiedy tylko wybrane osoby mogą edytować diagramy.

Innym rozwiązaniem są darmowe narzędzia do rysowania diagramów, którym jednak brakuje funkcjonalności, przez co wydłuża się czas potrzebny na modelowanie. I tak w kółko…

A do tego dochodzi jeszcze kompatybilność wsteczna, gdy po kilku latach chcesz otworzyć diagram przygotowany przy użyciu dużo starszej wersji. Nie zawsze to się udaje.

Brak automatycznej weryfikacji i innych automatyzacji

Większość nawet dobrych narzędzi nie ma zbyt wielu mechanizmów wspierających projektowanie. Chodzi na przykład o automatyczne weryfikowanie poprawności danego diagramu, czy generowanie diagramu na podstawie innych artefaktów (np. kodu źródłowego).

Takie rozwiązania pozwalałyby zaoszczędzić naprawdę sporo czasu.

Diagramy jako kod – o co chodzi?

Czy podejście „diagramy jako kod” może być rozwiązaniem tych problemów? Myślę, że tak!

O co w tym chodzi?

Diagram jako kod powstaje w formie pliku tekstowego. Możesz więc przygotować taki diagram nawet w notatniku, chociaż oczywiście istnieją lepsze metody. Jeżeli tak przygotowany plik ma prawidłową strukturę, to po otworzeniu go w odpowiednim narzędziu zostanie wygenerowany diagram.

Czyli narzędzie służy do tego, żeby zamieniać tekst w diagram, a nie żeby rysować w nim diagramy. To ogromna różnica.

Być może brzmi to dziwnie, ale ma sporo zalet. Już wyjaśniam jakie.

Automatyczne rysowanie diagramów zapisanych jako kod

Elementy nie przesuwają się w sposób niekontrolowany, ponieważ…wcale nie da się ich przesuwać. Narzędzie samo generuje model i decyduje o tym jak, połączyć poszczególne elementy.

Projektant czy analityk nie traci więc ani sekundy na to, żeby naprawiać rozjazdy na diagramach. Cały dostępny czas poświęca na zbudowanie odpowiedniego modelu.

Czy to nie wspaniałe?

Edytowanie diagramów bez bólu głowy

Powiedzmy, że po roku trzeba zmodyfikować diagram. Na przykład zamienić jeden element na dwa inne. Czy jest to trudne? Zupełnie nie!

Wystarczy odszukać miejsce w pliku tekstowym (Ctrl+F), w którym występuje stara nazwa, a następnie ją edytować i dodać drugi, analogiczny element. Na koniec jeszcze raz generujesz diagram i gotowe.

Zupełnie nie zastanawiasz się, czy ta zmiana nie zburzy czytelności diagramu. Działasz na poziomie merytorycznym, a resztę oddajesz w ręce narzędzia.

Jakie narzędzia są potrzebne do edytowania diagramu zapisanego w formie kodu?

W przypadku klasycznych narzędzi pisałem o kosztownych licencjach. Diagramy jako kod możesz pisać w czymkolwiek, czyli za darmo. Do budowania diagramów świetną opcją jest całkowicie darmowy PlantUML, który możesz wykorzystywać w też darmowym Visual Studio Code z rozszerzeniem do PlantUML.

Ale jeżeli ktokolwiek z osób przeglądających modele będzie chciał poprawić literówkę, to nie musi nic instalować. Otwiera plik tekstowy, wyszukuje dane słowo i zmienia na inne, poprawne. Zapisuje i już. Przy kolejnym generowaniu diagramów powstanie wersja z poprawką.

Tak przygotowane diagramy bez problemu dodasz do repozytorium na git, więc wprowadzanie zmian będzie bezpieczne i pod pełną kontrolą.

Diagram jako kod – możliwości automatyzacji

Największym plusem diagramów jako kod jest możliwość automatyzacji. Po pierwsze, składnia wymusza w jakimś stopniu poprawność i spójność diagramów. To jest taki podstawowy poziom weryfikacji.

Po drugie, skoro diagram jest zwykłym tekstem, to możesz z nim zrobić dowolne rzeczy. Wystarczy, że napiszesz prosty program np. w Pythonie, który sprawdzi pewne reguły. Na przykład, czy nazwy obiektów są zawsze z dużej litery albo czy nie istnieją kroki w procesie bez powiązań do innych aktywności.

I wreszcie po trzecie, czyli generowanie diagramów z kodu lub innych źródeł. To jest ogromna przewaga podejścia „diagramy jako kod” względem tradycyjnych aplikacji. Ten trend nabiera rozpędu i za kilka lat stanie się prawdopodobnie standardem. A wtedy już nigdy więcej nie trzeba będzie aktualizować dokumentacji ręcznie. Diagramy same się zaktualizują w wyniku zmian w kodzie źródłowym.

W tym ostatnim temacie polecam śledzić polski projekt P3 Model. Zapowiada się rewolucyjny produkt!

Czy są jakieś wady?

Diagramy jako kod mają też oczywiście pewne wady:

• nieco dłuższy czas nauki niż w przypadku narzędzi do rysowania diagramów, które wystarczy uruchomić i można od razu zacząć budować diagramy,
• bywa tak, że trzeba się sporo nagimnastykować, żeby osiągnąć oczekiwany efekt (jeżeli modelujesz np. wielokrotne zapętlenia itp.),
• czasami diagram się nie chce zbudować i nie jest do końca jasne co naprawić.

Przykłady

Teraz pora na konkrety!

Diagram aktywności jako kod

Przykładowy diagram aktywności zapisany jako kod w PlantUML wygląda tak:

@startuml 
title Proces płatności
start
:Zainicjowanie płatności;
repeat :Wybór medoty płatności;
    if (Płatność punktami?) then (Tak) 
        :Próba dokonania płatności za 
        pomocą salda punktów;
    else (Nie)
        :Przekierowanie do bramki płatności;
        :Próba dokonania płatności 
        w zewnętrznej bramce;
    endif
repeat while (Płatność z sukcesem?)  is (<color:red>Nie) -[#red]-> 
->Tak;
:Aktualizacja statusu zamówienia;
note left: Dowolny komentarz...
stop
@enduml

Efekt wywołania tego kodu jest następujący:

Co znaczą poszczególne linie:

• @startuml i @enduml – oznaczają początek i koniec diagramu. Wszystko poza start i end nie jest uwzględniane przy budowaniu diagramów.
• title – to tytuł wyświetlany na diagramie, dowolny tekst.
• start i stop – początkowy i końcowy element diagramu aktywności (czarne kropki).
• : (dwukropek) – oznacza krok w procesie.
• repeat, if – pętle i warunki do rozgałęziania diagramów. Szczegóły składni znajdziesz na stronach PlantUML.
• <color:red>Nie – w ten sposób można zmieniać kolor etykiet.
• -[#red]-> – w ten sposób można zmienić kolor strzałek.
• ->Tak – oznacza strzałkę z etykietą „Tak”.
• note left: – dodaje notatkę po lewej stronie elementu opisanego wyżej (można dodać „right” lub bez wskazania strony).

Więcej przykładów i cała specyfikacja jest na: https://plantuml.com

Możesz też sprawdzić możliwości PlantUML bez instalowania czegokolwiek, wybierając opcję „Online Server” na stronie https://plantuml.com.

Zobacz diagramy jako kod w akcji

Czy w diagramach jako kod można poszczególne elementy używać wielokrotnie?

Tak, w PlantUML możesz importować na przykład klasy z jednego pliku, do innego.

Zobacz to w akcji:

---