W pewnym momencie w każdym procesie tworzenia oprogramowania, w który jesteśmy zaangażowani, może zajść potrzeba stworzenia diagramów architektonicznych. Niezależnie od tego, czy stosujemy formalny model architektoniczny (np. Kruchten 4 +1, Różański i Woods, itp.), czy nie, istnieje potrzeba udokumentowania niektórych części aplikacji poprzez tworzenie diagramów. W architekturze oprogramowania takie diagramy są tworzone zgodnie z widokami związanymi z konkretnym punktem widzenia, który może być częścią modelu, ale w bieżącym artykule wolę posługiwać się terminem "diagram architektoniczny" i nie chcę być zbyt formalny; wszystkie pozostałe aspekty nie są tutaj objęte.

Opierając się na moim doświadczeniu jako architekta oprogramowania i trenera technicznego, istnieje wiele rozbieżności w sposobie tworzenia diagramów architektonicznych, w zależności od projektu, zespołu projektowego i programisty. Widziałem już wiele problemów dotyczących niespójności, fragmentacji i szczegółowości renderowanych informacji oraz wyglądu diagramów. W porównaniu do modelu architektonicznego, który musi być formalny i wystandaryzowany, diagramy niekoniecznie muszą być sformalizowane lub zgodne z określonym standardem.

Niemniej jednak, diagramy powinny być samoopisowe, spójne, wystarczająco dokładne i połączone z kodem. Dlatego ważne jest, aby każdy architekt lub inżynier oprogramowania polegał na kilku wytycznych podczas tworzenia diagramów architektonicznych, które będą wspólną podstawą komunikacji architektury aplikacji w czasie (np. struktura, elementy, relacje, właściwości, zasady) oraz między różnymi zainteresowanymi stronami mającymi różnorodne zaplecze techniczne i problemy.

Powszechne pułapki podczas projektowania diagramów architektonicznych

Zanim zacznę szczegółowo omawiać potencjalne problemy, chciałbym przytoczyć analogię do angielskiego idiomu: "jeden obraz wyraża więcej niż tysiąc słów". Zgodnie z definicją w wikipedii, niniejszy idiom "odnosi się do pojęcia, że złożony pomysł może być przekazany za pomocą zaledwie jednego nieruchomego obrazu, a także że obraz przedmiotu przekazuje jego istotę lub znaczenie skuteczniej niż opis". Ta sama koncepcja odnosi się do diagramu architektonicznego: jeśli diagram stawia więcej pytań, niż odpowiedzi - nie jest on dobrze stworzony. Nie pozwól, aby diagram architektoniczny wymagał tysięcy słów lub wyjaśnień!

Przykład nieprawidłowego diagramu architektonicznego.  Zawiera większość problemów opisanych niżej.

Prześledźmy teraz listę pułapek, które mogą utrudnić proces prawidłowego tworzenia diagramów architektonicznych.

Co oznacza blok lub kształt?

• Użycie dowolnego rodzaju bloku lub kształtu, które nie jest odpowiednio udokumentowane, może powodować wiele interpretacji. Może być ono powiązane z fragmentem danych, częścią kodu lub procesem. Prosty blok w diagramie może wywołać wiele wątpliwości i ważne, aby ich uniknąć poprzez wyraźne dodanie szczegółów dotyczących bloku lub kształtu w legendzie diagramu. 
  

Co reprezentują różne krawędzie kształtu?

• Każda krawędź kształtu (np. przerywana, kropkowana, itp.) może zostać źle zrozumiana w przypadku źle wykonanego diagramu. Czy konkretna krawędź odnosi się do konkretnego typu komponentu (np. linia przerywana odnosi się do kontenera, mikroserwisu, warstwy itp.), czy może jest to wybór projektującego, który preferuje bogaty wygląd i styl? Unikaj tego typu niejasności, podając dokładne dane w legendzie diagramu podczas wyboru wielu krawędzi lub krawędzi niestandardowych.
  

Co oznacza linia lub strzałka?

• Linia lub strzałka może być interpretowana jako przepływ danych (np. dane przepływają z systemu A do systemu B) lub jako relacja między elementami (np. komponent A zależy od komponentu B). W większości przypadków relacje lub strumienie danych reprezentowane przez strzałki rozchodzą się w różnych kierunkach i ważne jest, aby wyraźnie zapisać to w legendzie diagramu.
  

Jaki jest typ komunikacji / powiązania wskazany przez linię lub strzałkę?

• Nawet jeśli linia odnosi się do przepływu danych lub relacji między komponentami, typ komunikacji (np. w przypadku przepływu danych) lub typ powiązania (np. w przypadku relacji) oznaczony przez tę linię lub strzałkę musi być szczegółowy. Na przykład, jeśli linia reprezentuje przepływ danych, komunikacja może być synchroniczna lub asynchroniczna, lecz jeśli linia odnosi się do relacji, może być reprezentowana przez zależność, dziedziczenie, implementację itp. Wszystkie te szczegóły muszą występować w legendzie diagramu.
  

Co oznacza ten kolor?

• Użycie polikolorowego diagramu "perrot" (np. wielokolorowe pola, linie) bez odpowiednio udokumentowanego powodu może budzić wiele pytań (np. dlaczego niektóre pola są zielone, a inne czerwone? Dlaczego niektóre linie są czarne, a inne niebieskie?). Kolorystyka jest mniej ważną rzeczą w diagramie, a użycie bogatej liczby kolorów nie dostarcza dodatkowej treści ani cennych informacji. Diagram powinien być także wystarczająco zrozumiały i odpowiednio zaprojektowany dzięki wykorzystaniu tylko czarnego i białego koloru, chyba że istnieje ścisła wytyczna, aby podkreślić niektóre części diagramu przy użyciu wybranych kolorów.
  

Brak zależności między elementami diagramu lub pojedynczymi obiektami

• Brak zależności między elementami lub pojedynczymi obiektami w diagramie może wywołać poczucie niekompletności. Zarówno z perspektywy strukturalnej jak i behawioralnej, każdy element lub jednostka powinny opierać się na relacji (reprezentowanej przez linię lub strzałkę) z inną częscią systemu reprezentowaną przez inny element. 
  

Wprowadzające w błąd/ nieudokumentowane akronimy lub zbyt niejasne/ogólne terminy

• Podczas użycia etykiety dla elementu w diagramie zaleca się, aby nie używać żadnego wprowadzającego w błąd lub nieudokumentowanego akronimu, który mógłby spowodować nieporozumienie. Sekwencja liter sama w sobie (na przykład TFH, RBPM) nie ma żadnego znaczenia bez odpowiedniego wyjaśnienia elementu diagramu lub, jeszcze lepiej, w legendzie diagramu (np. TFH - ticket feet handler, RBPM - rates business process manager).
• Kolejna charakterystyka nazewnictwa elementów w diagramie odnosi się do terminów wyjątkowo niejasnych lub ogólnych (np. business logic, integration logic), które nie dostarczają zbyt wielu cennych informacji, ponieważ ich nazwy nie są wystarczająco samoopisowe. Ten problem może również wystąpić na poziomie kodu, i dlatego moja propozycja to używanie nazw wyjaśniających i sugestywnych oraz przestrzeganie zasad czystego kodu.

Wyszczególnienie technologii, struktur, języków programowania lub języków sktyptowych, IDE lub metodyki rozwoju na diagramie

• Projektowanie architektoniczne nie jest związane lub zasadniczo oparte na żadnej technologii, strukturze, języku programowania lub języku skryptowym, IDE lub technologii rozwoju. Wszystko to pojawia się później w procesie, aby pomóc w budowie architektury, lecz nie są one punktem centralnym. Nie należy ich włączać do diagramów, lecz umieścić w opisie architektonicznym, podając racjonalne uzasadnienie ich wyboru. 
  

Mieszać elementy wykonawcze z elementami statycznymi na jednym diagramie

• Elementy wykonawcze (np.wątki, procesy, maszyny wirtualne, kontenery, usługi, zapory, repopozytoria danych itp.) nie są obecne podczas kompilacji i zaleca się unikanie mieszania tych elementów z elementami statycznymi (np. komponenty, pakiety, klasy) na tym samym diagramie. Istnieją specjalne typy diagramów (np. diagram współbieżności, diagram wdrożenia), które koncentrują się głównie na elementach wykonawczych i ważne jest rozróżnienie tych dwóch kategorii elementów oraz, w miarę możliwości, uniknięcie ich mieszania.
  

Unikanie wyrażeń takich jak "opiszę to za pomocą słów" lub "wyjaśnię to później"

• Wszystko, co nie jest opisane w diagramie, jest nieobecne i nie należy dostarczać ustnych informacji uzupełniających diagram. Dlaczego? Ponieważ wszystkie wyjaśnienia ustne, które nie wchodzą w skład diagramu, zostaną utracone, a następnie, gdy diagram bedzie odczytywany przez innych zainteresowanych (np. programista, architekt), nie bedą oni świadomi tych wyjaśnień. Spróbuj umieścić wszystkie niezbędne szczegóły w diagramie, aby uniknąć potrzeby dalszych wyjaśnień. 
  

Kolidowanie różnych poziomów szczegółowości lub poziomów abstrakcji

• Dodawanie elementów związanych z różnymi poziomami abstrakcji na tym samym diagramie może powodować konflikt, ponieważ są one postrzegane z różnych perspektyw. Na przykład, dodanie komponentów do architektonicznego diagramu kontekstowego lub klas do diagramu wdrożenia może odbiegać od celu samego diagramu. Tworząc diagram, staraj się trzymać jednego poziomu abstrakcji. 
  

Zbyt zawiłe lub ogólnikowe diagramy próbujące przedstawić zbyt wiele informacji lub niedostateczny poziom szczegółowości diagramów

• "Wszystko powinno być tak proste, jak to tylko możliwe, ale nie prostsze" to dobrze znany cytat Alberta Einsteina. Dotyczy to również schematów architektonicznych; poziom i szczegółowość zgromadzonych informacji powinny być odpowiednio dobrane. To nie jest łatwe; zależy od zastosowanego modelu architektonicznego, doświadczenia architekta i złożoności systemu. 
  

W drugiej części artykułu przyjrzymy się wytycznym, których należy przestrzegać podczas tworzenia diagramów architektonicznych, a także sposobie ich aktualizacji na bieżąco.

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