Log decyzji dotyczących architektury rozwiązania (ADR)

Jedną z najtrudniejszych rzeczy w projektach informatycznych jest utrzymywanie aktualnej dokumentacji do kodu jak i całego rozwiązania. Nie ma się co oszukiwać ani Ty ani ja tego robić nie lubimy. Sami wiemy do czego do może doprowadzić…

// This method returns true
public int IsActive

Jak samo dokumentowanie kodu ma swoje problemy i różne rozwiązania tak już decyzje, dlaczego kod ma taką strukturę a nie inną kompletnie umyka uwadze zarówno programistów jak i architektów. Dobra, tfu, nie umyka, ten dokument 200 stronicowy co był stworzony 2 lata temu opisuje strukturę rozwiązania, które właśnie teraz piszemy… W trakcie tych dwóch lat dużo rzezy się wydarzyło i ten cały dokument 200 stronicowy do którego już nikt nie zagląda jest o 4 litery potłuc.

Jakakolwiek skomplikowana forma opisu architektury mija się z celem – nie będzie ona ani aktualizowana, ani przeglądana i pewnie zniknie z radarów do momentu, kiedy będziemy chcieli wprowadzić nową osobę do projektu. Fajnie, że na początku powstała i dała wytyczne lub nakreśliła kierunek rozwoju, jednak jak to bywa z rozwojem: trzeba nim sterować i podejmować decyzję w trakcie „dorastania”. Czyli to co trafi do nowej osoby to tylko i wyłącznie zapisy jak to by fajnie mogło wyglądać jednak do rzeczywistości to może się teraz mieć nijak.

Potrzebujemy więc czegoś co nam pomoże szybko i skutecznie opisywać i rejestrować decyzję podejmowane w projekcie. Coś co ma zając mało czasu, ma być silnie powiązane z kodem i z naszym repozytorium to czytając od początku do końca dam nam w pełni pogląd na to, dlaczego nasza aplikacja ma taką a nie inną strukturę i architekturę. To tam powinna się znaleźć odpowiedź, dlaczego zamiast Query wykorzystaliśmy w innym miejscu Service albo dlaczego nie mamy nigdzie Random tylko RandomProvider czy też, dlaczego komendy nazywamy Modifiers i co oznacza Command w naszym kontekście czy też, dlaczego wybraliśmy Nancy zamiast ASPNET Core. Takie informacje zamieniają WTF na odpowiedź z rozwinięciem, dlaczego coś zostało tak a nie inaczej rozwiązane. A to już daje BARDZO dużo, bo pozwala zrozumieć rozwiązanie nie pod względem „jak ono działa” ale dlaczego „ono działa tak a nie inaczej”.

Taki zapis decyzji nosi piękną nazwę Architecture Decision Log (ADL) i składa się on z naszych decyzji: Architecture Decision Record (ADR) i fajnie jakby on był naprawdę powiązany z naszym projektem. To co wchodzi w ADR to już tak naprawdę kwestia umowna, istnieją jednak różnego rodzaju szablony co w takim dokumencie powinno się zawrzeć.

Jednym z bardziej popularnych i najprostszym jest szablon stworzony przez Michael Nygard w 2011 roku, który opisuje on go w swoim wpisie na blogu. Szablon składa się z czterech części:

• Kontekst (context) – czyli czego dotyczy decyzja, motywacje itp.
• Decyzja (decision) – czyli podjęta decyzja jak rozwiązać dany problem
• Wynik/Skutki (consequences) – czyli jaki będzie rezultat wprowadzenia danej, podjęcia danej decyzji
• Statusu (status) – czyli czy decyzja została podjęta, cofnięta, czy to tylko propozycja.

Decyzje powinny być numerowane, to znaczy, że zaczynamy od 1 i kończymy na X – głównie po to byśmy mogli je czytać zgodnie z podejmowaniem, wiesz tak jak z ES, czytając od początku będziesz wiedział wszystko i znał aktualny stan.

Inne szablony mają dużo więcej opcji, bardzo fajne repozytorium zbierające różne szablony dostępne jest na github. Tam także znajdziesz informacje, o narzędziach które mogą Ci pomóc tworzyć takie dokumenty. Jednak piękno w ADR jest to, że ma być on prosty na tyle, że każdy może go stworzyć.

Oczywiście ADR może to być nawet plik txt załączony do projektu, do którego dodajemy po prostu kolejne decyzje. Ważne jest jednak by nie był on zbyt długi, nikt nie lubi czytać długich dokumentów ;)

Mając ADR będziemy wstanie odpowiedzieć na pytanie, dlaczego coś zostało tak a nie inaczej zaprojektowane, jak i wspomożemy nowe osoby w projekcie ze zrozumieniem naszego rozwiązania. W szczególności kiedy to nie my będziemy odpowiedzialni za jego utrzymanie.