W naszym pierwszym artykule opisaliśmy trudności, na które możemy się natknąć podczas tworzenia diagramów architektonicznych - od kolorystyki do mieszania elementów wykonawczych z elementami statycznymi aż po zbyt skomplikowane i zawiłe diagramy. Spójrzmy teraz na wskazówki, które należy mieć na uwadze.

Wytyczne dotyczące tworzenia diagramów

Oprócz wymienionych we wcześniejszym artykule pułapek, które muszą znaleźć się na liście kontrolnej w celu ich uniknięcia, istnieją również ogólne wytyczne dotyczące prawidłowego tworzenia schematów:

Wybierz optymalną liczbę diagramów

• Jak powiedział Philippe Kruchten, "architektura jest złożoną bestią, a wykorzystanie jednego wzoru do przedstawienia architektury powoduje niezrozumiały semantyczny bałagan". Aby udokumentować nowoczesne systemy, nie możemy ograniczyc się do jednego rodzaju diagramu, ale podczas tworzenia diagramów architektonicznych nie zawsze wiadomo, jakie schematy wybrać i ile ich utworzyć. Przed podjęciem decyzji należy wziąć pod uwagę wiele czynników, takich jak charakter i złożoność architektury, umiejętności i doświadczenie architekta oprogramowania, dostępny czas, ilość pracy niezbędnej do ich utrzymania, a także to, co ma sens lub jest pożyteczne w kontekście spraw zainteresowanych. Na przykład, inżynier sieciowy prawdopodobnie będzie chciał zobaczyć zautomatyzowany model sieci, zawierający hosty, porty komunikacyjne i protokoły; administrator bazy danych będzie zainteresowany tym, w jaki sposób system przetwarza dane, zarządza nimi i je dystrybuje itd. Na podstawie wszystkich tych aspektów zaleca się zebranie optymalnej liczby diagramów, nie ograniczając się w ilości.
• Jeśli liczba diagramów jest niewystarczająca (np. niepełna dokumentacja), niektóre elementy architektury mogą być ukryte lub nieudokumentowane; z drugiej strony, jeśli jest ich zbyt dużo (np. nadmierna dokumentacja), wysiłek potrzebny do utrzymania ich spójności, aktualizacji i niedouszczenia do fragmentacji może znacznie wzrosnąć.

Zachowaj spójność strukturalną i semantyczną w diagramach

• Każdy diagram powinien być spójny z pozostałymi pod względem pól, kształtów, obramowań, linii, kolorów itp. Strukturalny wygląd powinien być taki sam, aby każdy zainteresowany nie miał trudności w zrozumieniu diagramów tworzonych przez różnych programistów wewnątrz zespołu. Najlepiej jest trzymać się wspólnego narzędzia do diagramowania i używać go we wszystkich projektach.
• Z semantycznego punktu widzenia wszystkie te diagramy powinny być okresowo synchronizowane z ostatnimi zmianami kodu oraz między sobą, ponieważ zmiana jednego diagramu może mieć wpływ na inne diagramy. Ten proces może być uruchamiany ręcznie lub automatycznie za pomocą narzędzia do modelowania. Lepiej używać drugiego mechnizmu, jednak wiele zależy od rodzaju projektu - we wszystkich przypadkach chodzi o zachowanie spójności między diagramami i kodem, niezależnie od metody lub narzędzia. Simon Brown powiedział, że "diagramy nie są przydatne dla ulepszeń architektonicznych, jeśli nie są połączone z kodem", co podkreśla ideę semantycznej spójności.

Zapobiegaj fragmentacji diagramów

• Wiele diagramów może utrudniać zrozumienie opisu architektonicznego, lecz ma znaczący wpływ na jego wygląd. Efektem ubocznym może byc fragmentacja (na przykład dwa lub więcej diagramów ilustruje ten sam atrybut jakości - wydajność, skalowalność itp. - lecz każdy z nich jest indywidualnie niekompletny). W takich przypadkach zaleca się usunięcie diagramów, które nie odzwierciedlają odpowiednich atrybutów jakości (związanych z wymaganiami istotnymi pod wzgledem architektonicznym) lub, jeszcze lepiej, scalanie diagramów (np. współbieżność i wdrożenie).
  

Zapewnij możliwość śledzenia diagramów

• Bardzo ważna jest możliwość sprawdzenia historii diagramów, porównywania różnych wersji diagramów oraz łatwego powrotu do poprzedniej wersji. Przeszkodą może być użycie narzędzia do modelowania, które tego nie zapewnia. Najnowsze trendy w branży pozwalają na użycie prostego i intuicyjnego języka w postaci zwykłego tekstu do generowania diagramów, co wydaje się rozwiązywać problem śledzenia. Jeszcze jedną zaletą takiego podejścia jest to, że pośrednio zapewnia jednorodną strukturalną spójność między diagramami. 
  

Dodaj legendy przy diagramach

• Jeśli nie stosujesz standardowego języka opisu architektury (np. UML, ArchiMate), wyszczególnij każdy fragment diagramu w legendzie (np. pola, kształty, granice, linie, kolory, akronimy itp.). 
• W innym przypadku, po prostu dodaj w legendzie architektoniczny język opisu jako klucz w celu uniknięcia dodawania dodatkowych wyjaśnień, ponieważ każdy czytelnik zastosuje się do tej specyfiki języka, aby zrozumieć diagram.

Czy wybór języka opisu architektury (np. UML, ArchiMate) ma znaczenie?

Istnieje wiele opinii dotyczących właściwego języka opisu, który powinien zostać przyjęty w projekcie. Niektórzy mogą twierdzić, że UML jest sztywny i mało elastyczny dla modelowania projektu architektonicznego, z czym się zgadzam. Niemniej jednak w niektórych przypadkach może to być wystarczające dla dokumentacji podstaw architektury bez sięgania po jakiekolwiek funkcje rozszerzające UML, takie jak profile i stereotypy. Patrząc na inne języki opisu, widać, że ArchiMate w porównaniu z UML jest potężniejszy i nadaje się do modelowania systemów korporacyjnych; istnieje również BPMN, który jest szczególnie ukierunkowany na procesy biznesowe itp. Porównania mogą być kontynuowane, ale nie zamierzam dokonywać ich głębszej oceny, ponieważ nie jest to celem tego artykułu.

Kompleksowy i elastyczny język opisu architektury jest dużym krokiem naprzód, i to powinno być głównym kryterium przy jego wyborze. Jednak z mojej perspektywy, prawdziwa przyczyna znajduje się gdzieś indziej i jest związana z faktem, że dokumentacja architektoniczna nie jest tworzona. Ludzie często uważają ją za nudną, bezużyteczną lub bezcelową. Liczba projektów bez dokumentacji lub z niewłaściwą dokumentacją jest ogromna. Nie sądzę, że ludzie intensywnie tworzą lub angażują się w tworzenie diagramów architektonicznych za pomocą niewłaściwego języka opisu, i gdyby mieliby go zastąpić lepszym, rezultaty byłyby inne. Nie, ludzie nie tworzą ŻADNEJ dokumentacji architektonicznej (włączając w to schematy architektoniczne), a co gorsza, wiekszość z nich nie ma pojęcia o tym, jak prawidłowo ją tworzyć. To są właśnie rzeczy, które musimy rozwiązać w pierwszej kolejności - aby zrozumieć, dlaczego dokumentacja ma znaczenie i jak ją właściwie stworzyć (poprzez szkolenia dla inzynierów oprogramowania); i wtedy wybór odpowiednich narzędzi przyjdzie naturalnie.

W jaki sposób diagramy mogą być uaktualniane podczas opracowywania systemu i wprowadzania w życie zmian

Istnieje kilka podejść, w jaki sposób aktualizować diagramy; poniżej przedstawię trzy z nich. Pierwsze i najłatwiejsze podejście to automatyczne generowanie diagramów z kodu źródłowego. Gwarantuje to zgodność wszystkich diagramów z kodem. Niestety, przy istniejących narzędziach nie jest to jeszcze w pełni możliwe (przynajmniej według mojej wiedzy), ponieważ aktualne narzędzia nie są w stanie tworzyć żadnego rodzaju prawidłowego i znaczącego diagramu opartego tylko i wyłącznie na kodzie źródłowym, bez znaczącej manualnej interwencji. Len Bass powiedział: "Idealne środowisko programistyczne to takie, dla którego dokumentacja jest dostępna w zasadzie za darmo, po naciśnięciu przycisku" oraz domyślnie i automatycznie generuje diagramy, lecz jeszcze nie osiągnęliśmy tego poziomu.

Drugie podejście polega na zaprojektowaniu diagramów za pomocą dedykowanego narzędzia, które następnie generuje szkielety kodu źródłowego (na przykład komponenty / pakiety z granicami, interfejsy API) używane później przez programistów do wypełnienia kodu. W ten sposób każda zmiana w architekturze musi najpierw zostać uruchomiona na samym diagramie, co automatycznie generuje lub aktualizuje szkielet kodu.

Ostatni przypadek polega na ręcznym aktualizowaniu diagramów za każdym razem, gdy wdrażana jest nowa funkcja, która ma wpływ na projekt architektoniczny. Aby upewnić się, że wszystkie zmiany w kodzie są odzwierciedlone na diagramach, zaleca się, aby zaktualizować diagramy jako część definicji wykonanej w procesie projektowania. Ten scenariusz jest mniej zalecany, ponieważ może wywołać przestarzałe lub niespójne diagramy (np. programiści często zapominają lub nie są w nastroju do aktualizacji diagramów) i niestety, zdarza się to nadal w większości projektów.

Biorąc pod uwagę istniejące narzędzia, zalecam połączenie - automatyczne mieszanie i ręczne tworzenie diagramów. Na przykład, spróbuj automatycznie generować diagramy, które można rozsądnie renderować za pomocą narzędzi opartych na kodzie źródłowym bez większych trudności (np. zbyt zawiła lub pozbawiona znaczenia informacja). W tej kategorii możemy uwzględnić zarówno diagramy o dużej zmienności (np. bardziej podatne na częste zmiany rozwojowe, zazwyczaj o niższej abstrakcji) lub, przeciwnie, diagramy statyczne. Niektóre z tych diagramów mogą odnosić się do diagramów kontekstowych, referencyjnych diagramów architektury, diagramów pakietów, diagramów klas, diagramów elementów itp. Niemniej jednak, w niektórych przypadkach nie jest oczywiste, opierając się tylko na kodzie źródłowym, w jaki sposób system spełnia pewne cechy jakościowe (np. dostępność, skalowalność, wydajność), dlatego automatyczne tworzenie diagramów nie jest wystarczającą opcją i musi być uzupełnione przez manualnie modelowane diagramy. Niektóre przykłady tych diagramów obejmują diagramy sekwencji, diagramy stanu, diagramy współbieżności, diagramy wdrożenia, diagramy operacyjne itp.

Jakie komplikacje (lub uproszczenia) zachodzą w diagramach architektonicznych w przypadku nowoczesnej architektury (np. mikroserwisów)?

Mikroserwisy lub jakikolwiek inny nowoczesny styl architektoniczny (np. bez użycia serwerów, sterowany zdarzeniami) steruje tylko strukturą systemu, sposobem, w jaki komponenty komunikują się nawzajem (np. relacjami między nimi) i jakie zasady nimi rządzą. Osobiście nie sądzę, że styl architektoniczny powinien zmienić sens diagramu lub koncepcje związane z tworzeniem diagramów (i domyślnie z opisem architektonicznym), ani treści diagramu. Niemniej jednak, gdy mówimy o nowoczesnych architekturach systemów, zwykle o wyższych poziomach złożoności w porównaniu do starych i klasycznych systemów (np. monolit), trzeba przyznać, że mają one zdecydowany wpyw na opis architektoniczny i bezpośrednio na diagramy, w tym znaczeniu, że istnieje wiele kwestii do rozważenia. Takie kwestie mogą polegać na ustaleniu liczby rozposzonych komponentów (np. rozproszonych mikroserwisów), rodzaju każdego komponentu, sposobu, w jaki komponenty komunikują się ze sobą (np. granice, interfejsy API, komunikaty), ich cyklu życia i kto posiada każdy każdy.

Biorąc to wszystko pod uwagę, widoki rejestrujące dekompozycję systemu oraz rozwój i operacyjność powinny być uwzględnione domyślnie. Dla przykładu, wyobraź sobie system z imponującą liczbą mikroserwisów; w takim przypadku liczba diagramów może znacząco wzrosnąć, ponieważ każdy mikroserwis może mieć własny zestaw schematów. Kwestie dotyczące spójności (np. zmiana API jednej usługi wpływa na inne usługi X, dlatego wszystkie dotknięte diagramy muszą zostać zaktualizowane), fragmentacji (np. wysoka dostępnosć lub wydajność między rozproszonymi usługami nie jest skonsolidowana w jednym schemacie) lub zagadnień przekrojowych (np. kto jest odpowiedzialny za zilustrowanie w sposób skonsolidowany aspektów takich jak monitorowanie lub bezpieczeństwo elementów w całym systemie) mogą nie być proste. Oprócz tego mogą pojawić się wyzwania związane ze współistnieniem i współpracą zespołów podczas opracowywania projektu, a nawet później, w celu jego utrzymania.

Podsumowując, nowoczesne systemy o złożonych architekturach mogą dostarczyć dodatkowych problemów, które mogą prowadzić do komplikacji nawet na poziomie diagramów.

Chcesz poprawić swoje umiejętności w zakresie architektury oprogramowania?
Sprawdź nasz kurs Podstawowe praktyki architekta oprogramowaniag