W dzisiejszym świecie rozwoju oprogramowania, gdzie złożoność systemów stale rośnie, kluczowe znaczenie ma skuteczna dokumentacja decyzji architektonicznych. Dzięki temu podejściu zespoły mogą nie tylko utrzymywać spójność projektu, ale także łatwiej zarządzać zmianami. W tym kontekście pojęcia takie jak Architecture Decision Log (ADL) i Architecture Decision Record (ADR) odgrywają fundamentalną rolę. Artykuł ten wprowadzi w koncepcję ADL i ADR, omówi ich główne atrybuty oraz zasugeruje sposoby implementacji.
Co to jest ADL i ADR?
Architecture Decision Log (ADL) jest zbiorczym dokumentem lub repozytorium, które zawiera wszystkie Architecture Decision Records (ADR) dotyczące projektu. Jest to miejsce, gdzie zespoły mogą śledzić i zarządzać kluczowymi decyzjami architektonicznymi.
Architecture Decision Record (ADR), z kolei, to dokument skupiający się na pojedynczej, istotnej decyzji architektonicznej wraz z kontekstem i konsekwencjami tej decyzji. ADR pomaga w dokumentowaniu kluczowych decyzji, które wpływają na strukturę i działanie systemu.
Główne atrybuty ADR
ADR charakteryzują się kilkoma kluczowymi atrybutami, które zapewniają ich użyteczność i efektywność:
Niemutowalność rekordu - Po zatwierdzeniu, ADR nie powinien być modyfikowany. Zapewnia to, że historia decyzji jest stała i przejrzysta.
Rekord zawiera czas podjęcia decyzji - Data i czas decyzji są kluczowe dla zrozumienia kontekstu, w którym została ona podjęta.
Opisuje dokładnie jedną decyzję - Każdy ADR powinien dotyczyć tylko jednej konkretnej decyzji, co zapobiega konfuzji i sprawia, że dokumentacja jest czytelniejsza.
Zawiera obecną sytuację i kontekst - Opisuje aktualne warunki, które wpływają na projekt lub system, podkreślając znaczenie decyzji.
Zawiera porównanie kilku opcji - ADR powinien opisywać alternatywne rozwiązania, które były rozważane przed podjęciem ostatecznej decyzji, wraz z uzasadnieniem wyboru.
Zawiera wpływ driverów architektonicznych na decyzję - Kluczowe motywacje czy wymagania, które miały wpływ na decyzję, są istotne dla zrozumienia wyborów projektowych.
Zawiera konsekwencje podjętej decyzji - Konsekwencje, zarówno pozytywne, jak i negatywne, powinny być dokładnie opisane, aby zrozumieć długoterminowy wpływ decyzji na projekt.
Implementacja ADR
Przykład z życia:
Załóżmy, że zespół projektowy stoi przed wyborem technologii do obsługi bazy danych. Możliwe opcje to SQL i NoSQL. Po analizie wymagań projektu, zespołowych preferencji, możliwości skalowania i zarządzania danymi, zespół decyduje się na SQL. Decyzja ta jest dokumentowana jako ADR, gdzie opisano dlaczego odrzucono NoSQL (np. z powodu braku potrzebnych transakcji), jakie są przewidywane korzyści z wybranej technologii oraz jakie są potencjalne ryzyka i ograniczenia.
Wdrażanie jako kod:
Do tworzenia i zarządzania ADR można użyć narzędzi takich jak adr-tools
aby wygenerować szablony decyzji. Dzięki temu ADR mogą być wersjonowane razem z kodem źródłowym i łatwo dostępne dla całego zespołu.
przykład pliku markdown z opisaną decyzją
Narzędzie adr-tools
jest popularnym środkiem do zarządzania Architecture Decision Records (ADR) w projektach programistycznych. Umożliwia ono szybkie tworzenie, zarządzanie i przeglądanie ADR-ów w formie tekstowej, co jest szczególnie przydatne w środowiskach, gdzie dokumentacja i przejrzystość decyzji są kluczowe.
Instalacja adr-tools
Najpierw musisz zainstalować adr-tools
. Narzędzie to jest dostępne na GitHubie i można je zainstalować na systemach Unix i podobnych (takich jak macOS czy Linux) za pomocą prostego skryptu instalacyjnego. Oto jak to zrobić:
Inicjowanie repozytorium ADR
Po zainstalowaniu narzędzia, przejdź do głównego katalogu swojego projektu i zainicjuj repozytorium ADR:
To polecenie utworzy katalog doc/architecture/decisions
, gdzie będą przechowywane wszystkie ADR-y. W tym katalogu zostanie również utworzony pierwszy ADR, który dokumentuje decyzję o używaniu ADR-ów.
Tworzenie nowego ADR
Aby utworzyć nowy ADR, użyj polecenia adr new
. Na przykład, aby utworzyć ADR dotyczący wyboru frameworka do testów, możesz użyć:
To polecenie stworzy nowy plik ADR w katalogu decyzji, z przydzielonym kolejnym numerem i podanym tytułem. Plik ten będzie zawierał szablon, który możesz wypełnić, opisując kontekst, decyzję, konsekwencje i inne kluczowe aspekty.
Przeglądanie i zarządzanie ADR-ami
adr-tools
oferuje również możliwości przeglądania istniejących ADR-ów i zarządzania nimi:
- Wylistowanie wszystkich ADR-ów:
adr list
- Pokaż szczegóły ADR:
adr view NUMER
- Ustalenie, że jeden ADR zastępuje inny:
adr link NUMER supercedes INNY_NUMER
Ciekawostka - Confluence:
Atlassian Confluence oferuje szablon "Decision" w ramach swojej funkcjonalności, co pozwala zespołom na tworzenie i zarządzanie ADR w bardziej zintegrowanym środowisku korporacyjnym.
Podsumowanie
Dokumentacja decyzji architektonicznych za pomocą ADL i ADR jest nie tylko praktyką wzmacniającą procesy decyzyjne, ale również sposobem na budowanie bardziej przewidywalnych i zarządzalnych systemów informatycznych. Przez odpowiednie dokumentowanie kluczowych decyzji, zespoły mogą lepiej przewidywać skutki swoich wyborów, co w długoterminowej perspektywie przekłada się na większą efektywność i skuteczność projektów.