Architecture Decision Record / Decision Log

Czy byliście kiedyś w sytuacji, że dołączyliście do istniejącego już projektu, zagłębiliście się w jego kod i architekturę, a następnie uznaliście, że to jest bez sensu? Że ktoś dał mocno ciała wybierając architekturę pod projekt albo podejmując inne ważne decyzje? Jednak nie macie kogo o to spytać, bo żadna z osób, które podejmowały te decyzje, już w tym projekcie nie pracuje?
Może nawet postanowiliście zrobić refaktoryzację i po kilku godzinach/dniach okazało się, że jednak początkowe rozwiązanie było lepsze, bo nie wzięliście pod uwagę jednego małego szczegółu albo skrajnego przypadku? Może nie byliście pierwsi, którzy tego próbowali? A może jak wy odejdziecie z projektu, to przyjdą kolejni, którzy też będą próbowali tego samego?

Z drugiej strony może to wy byliście osobą, która była obecna przy tworzeniu tej architektury, przy podejmowaniu tych decyzji? Nie byliście z nich do końca zadowoleni, ale rozumieliście, że na dany moment to było najlepsze wyjście. Wraz ze swoim zespołem staraliście się wybierać najlepsze z możliwych rozwiązań.
Następnie po jakimś czasie do projektu dołączył ktoś nowy, kto zagłębiając się w kod i jego architekturę podsumowuje to jednym prostym pytaniem – kto wam to tak spartolił?
Oczywiście stajecie w pozycji obronnej i chcecie mu te wszystkie podjęte decyzje wyjaśnić (albo staracie się zrzucić winę za te decyzje na kogoś innego). Pomijając już ile to może kosztować czasu, to większości z tych decyzji możecie już po prostu nie pamiętać. Zapomnieliście już dlaczego w swoim projekcie zdecydowaliście się na rozwiązanie A, kosztem rozwiązania B, ale pamiętacie, że był jakiś powód. Tylko nie możecie sobie przypomnieć jaki…

Byłem w takich sytuacjach. Zarówno w pierwszej, jak i drugiej. Kiedyś myślałem, że tak po prostu jest, że tak wygląda proces wytwarzania oprogramowania. Nie byłem z tego zadowolony, ale nie wiedziałem co można zrobić, aby było lepiej.
Aż pewnego razu, usłyszałem o czymś takim jak Architecture Decision Record (inna nazwa to Decision Log) i to okazało się być rozwiązaniem na te wszystkie problemy.
Od tamtego czasu staram się we wszystkich moich projektach zachęcać innych do jego prowadzenia.

Architecture Decision Record

Jest to spisany zbiór ważnych decyzji, które zostały podjęte w projekcie.
Może zawierać on takie informacje jak:
– Kontekst, który wymusił podjęcie jakiejś decyzji.
– Decyzja, jaka została podjęta.
– Rozwiązania, które były brane pod uwagę.
– Powód wybrania danego rozwiązania.
– Konsekwencje wynikające z danego wyboru.
– Status mówiący o tym, czy decyzja już zapadła, czy jeszcze toczą się rozmowy.
– Data podjęcia decyzji.
– Autorzy, czyli lista osób, która brała udział w podejmowaniu decyzji.

Nie wszystkie z wymienionych elementów muszą się znaleźć w naszym spisie decyzji. Każdy powinien wybrać to, co w jego przypadku będzie potrzebne.
U mnie w projektach raz było to więcej elementów (a nawet wszystkie), raz mniej (np. tylko kontekst, decyzja, konsekwencje i status). Nie ma tutaj sztywnej reguły.

Przykład

Taki przykładowy może wyglądać następująco:

Context: We are planning to store data in a relational database. We need to have a possibility to make queries to this database (select/insert/update).
Decision: We decided to go with Entity Framework Core.
Solutions:
- Entity Framework Core: In EF Core writing simple queries should go really fast. Generating a complex query can be time-consuming.
- Stored procedures + dapper: Writing queries can be time-consuming, but performance is really good.
Reason: Our project seems to be a simple CRUD application. For now, we are not sure, that we will have complex queries.
Consequences: When we met a complex query we will need to take a look at the performance of this query.
Status: Approved.
Date: xx-xx-xxxx
Authors: Adrian Mularczyk, xxx 

Przykład takiego pełnego zbioru decyzji (nie mojego autorstwa) możecie znaleźć tutaj.

Zalety

Posiadając taki Architecutre Decision Record można w dowolnej chwili do niego zajrzeć i przypomnieć sobie, dlatego użyliśmy tego, a nie innego rozwiązania. Dlaczego podjęliśmy taką, a nie inną decyzję.
Dodatkowo gdy ktoś nowy dołączy do zespołu, to można mu taki zbiór decyzji pokazać, aby wiedział kiedy i dlaczego one zapadły. To nie tylko ułatwi wejście w projekt, ale również zaoszczędzi sporo czasu spędzonego na analizowaniu i rozmyślaniu.
W niektórych sytuacjach pomaga nawet przy podejmowaniu nowych decyzji czy wprowadzaniu zmian. Po prostu tworzymy nowy wpis, w którym opisujemy co nas boli i co możemy z tym zrobić. Inne osoby w wolnej chwili mogą wtedy bez problemu dopisać swoje przemyślenia. Gdy taki dokument już się rozrośnie, to można albo podjąć jakąś decyzję od razu, albo zorganizować spotkanie i na nim omówić problem wraz z rozwiązaniami.

Gdzie przechowywać?

Osobiście proponowałbym w repozytorium utworzyć folder 'ArchitectureDecisionRecord’ (albo 'Decisions’) i tam przechowywać zbiór wszystkich decyzji. Alternatywą może być trzymanie go w repozytorium w pojedynczym pliku, np. ’ ArchitectureDecisionRecord.txt’ albo nawet w 'README.md.’ Jeśli ktoś nie chce trzymać takich rzeczy w repozytorium albo lubi mieć dokumentację w jakimś osobnym miejscu, to nic nie stoi na przeszkodzie, aby na Confluence (albo innym narzędziu, na którym przechowujecie dokumentację) dodać stronę na której będzie znajdował się Architecture Decision Record.
Ważne jest jednak to, aby decyzje numerować – ułatwi nam to później odnoszenie się do nich.

Koszt

Możecie się zastanawiać jaki jest koszt prowadzenia takiego zbioru decyzji. O dziwo nie jest on jakiś duży. W większości przypadków sprowadza się on do spisania ustaleń ze spotkania albo wrzucenia wyników z poszukiwań.