Dokumentacja architektury

Pomimo tego, że każdy system informatyczny posiada architekturę niezależnie od tego czy została ona udokumentowana czy nie, to dobrą praktyką jest jej udokumentowanie. Stopień i sposób w jaki to robimy zależy od wielu czynników, chociażby od skali rozwiązania, metodyki wytwarzania oprogramowania itd.

Podstawowym dokumentem opisującym architekturę oprogramowania jest dokument opisu architektury (ang. Software Architecture Description, w skrócie SAD).

Co powinien zawierać SAD?

Aktualnie istniejące standardy nie precyzują co dokładnie powinien zawierać SAD. Wynika to przede wszystkim z tego, że trudno stworzyć jeden uniwersalny szablon dla de facto różnych systemów, które w dodatku posiadają różne grupy interesariuszy mających odmienne oczekiwania co do projektowanego rozwiązania. Tworząc SAD należy pamiętać o tym, że każdy system posiada dokładnie jedną architekturę, która może być zależnie od potrzeb udokumentowana (przedstawiona) na wiele sposobów.

Standardy czy też dobre praktyki tworzenia dokumentacji architektury dają nam wysokopoziomowe wytyczne jak powinien zostać zorganizowany dokument opisu architektury oraz co powinien zawierać. 

Tworząc dokumentację architektury należy przede wszystkim pamiętać o identyfikacji interesariuszy projektu. Opis architektury powinien być zrozumiały i precyzyjny dla tych grup interesu i odpowiednio adresować ich obszary szczególnego zainteresowania (ang. concerns). Pisząc o grupach interesu mam na myśli m.in. programistów, kierownictwo projektu, użytkownika rozwiązania, "biznes", klienta (zleceniodawcę/sponsora). Opis powinien być zrozumiały i jednoznaczny dla odbiorców, w przeciwnym razie to tak jakby go nie było. 

Dokument obowiązkowo musi zawierać ogólną wizję systemu, ale z drugiej strony opis musi być na tyle szczegółowy aby na jego podstawie można było np. rozpocząć pracę nad systemem. I tutaj pojawia się problem: jak udokumentować złożony system?


W jaki sposób udokumentować architekturę systemu?

Jednym z aktualnie propagowanych podejść jest dekompozycja systemu na widoki. W tym przypadku dokumentacja architektury systemu to zatem zbiór opisów jej widoków. Widok, najprościej mówiąc, to zbiór istotnych elementów systemu (ang. concerns) przedstawiony w ściśle zdefiniowany sposób. Sposób ten definiowany jest z kolei przez punkt widzenia architektury (ang. architecture viewpoint). Viewpoint'y, które należy brać pod uwagę w tworzonym opisie architktury to m.in.:

• otoczenie systemu (context viewpoint) - opisujący otoczenie i środowisko pracy systemu;
• funkcjonalność systemu (functional viewpoint) - przedstawiający elementy systemu dostarczające konkretnych funkcjonalności;
• rozmieszczenie systemu (deployment viewpoint);
• implementacji (implementation viewpoint);
• informacyjny (information viewpoint);
• ...

Bardzo ważne, na co należy zwrócić uwagę to spójność pomiędzy poszczególnymi widokami. Każdy z widoków przedstawia system z różnego punktu widzenia, jednak należy pamiętać, że to wciąż ten sam system. Na schemacie poniżej przedstawiono graficznie zależności pomiędzy opisem architektury, widokiem, punktem widzenia i interesariuszami.

Poza widokami, które przedstawiają nasz system z różnych puntów widzenia, w praktyce mamy do czynienia z takimi elementami systemu, które są wspólne dla wszystkich lub przynajmniej części widoków. Mam tutaj  na myśli takie aspekty jak:

• bezpieczeństwo;
• wydajność;
• dostępność;
• skalowalność;
• niezawodność;
• ...

Są to elementy architektury systemu, więc SAD powinien również zawierać wyżej wymienione aspekty. Można to zrealizować albo poprzez dodanie odpowiednich opisów w ramach konkretnych widoków lub poprzez utworzenie widoków dedykowanych.