Gjennom et produkts levetid gjøres det mange små eller større beslutninger knyttet til teknologi, design patterns, rammeverk og biblioteker. Når disse avgjørelsene tas gjøres det ofte en del vurderinger og det diskuteres en del rundt hva man bør velge, og hvorfor man ender opp på det valget man gjør, både i teamet og også kanskje utenfor.

For en som kommer ny inn på teamet og skal sette seg inn i kodebasen og systemet er det ikke alltid så enkelt å forstå hvorfor ting har blitt som det har blitt. Antagelig kan mange eksisterende teammedlemmer svare, men noen har kanskje forlatt teamet og de som er igjen husker kanskje ikke helt?

I denne artikkelen vil jeg snakke om Architecture Decision Records, og hvordan dette kan hjelpe deg til å dokumentere og synliggjøre hvilke valg som er tatt, og hvilke vurderinger som ble gjort, både for teamets del i dag og ikke minst for fremtiden.

Hva er Architecture Decision Records?

Architecture Decision Records (ADR), også kjent som Lightweight Architecture Decision Records er som navnet sier, en lettvekts måte å dokumentere ulike arkitekturbeslutninger som gjennomføres i teamet og produktet ditt.

Det er et relativt kort dokument, maks et par avsnitt, og lagres som markdown-filer sammen med kildekoden din i Git. Hva som skal til for å skrive en ADR er opp til teamet, men et tips er skrive det når man gjør såkalte "architecturally significant decisions", det vil si de litt større tekniske avgjørelsene.

Noen eksempler er hvilket web-rammeverk man tar i bruk, hva slags måte man henter hemmeligheter på, om man følger en spesiell applikasjonsarkitektur, har tatt i bruk spesifikke design patterns, eller om man benytter et rammeverk eller bibliotek som man ønsker å dokumentere bakgrunnen for.

Hvorfor trenger vi å dokumentere arkitekturvalg?

Som nevnt gjøres det mange arkitekturvalg når man utvikler og forvalter et produkt. Målet med ADR er å dokumentere for teamets del i dag og for fremtiden hvilke alternativer som har blitt vurdert, hvilke vurderinger man har gjort og hvilke valg man endte opp med.

Målet er å sikre at valg teamet har gjort er synlige og forståelig og gir utviklingsteamet, og fremtidige teammedlemmer innsikt i tanker og intensjoner og alternativer som har blitt diskutert. Det kan også fungere som et verktøy for andre team og resten av organisasjonen for å se hvilke valg et team har gjort og f.eks. la seg inspirere til å ta de samme valgene eller sette en felles retning.

Arkitekturen til et system endrer seg ofte over tid og man må kontinuerlig ta nye valg etter hvert som tiden går. ADR kan derfor være med å bidra til å forstå gamle valg som har blitt gjort og dermed vurdere nye valg i lys av disse.

Når man kommer inn som et nytt teammedlem kan det være noen valg som umiddelbart ikke gir helt mening. Hvis man har et sett med ADR-er hvor man har listet opp hvilke alternativer man har vurdert, hvilken kontekst man jobber i og hvorfor man har valgt som man har gjort, kan det være at man i større grad forstår avgjørelsen som har blitt tatt, eller at det blir enklere å argumentere og diskutere for hvorfor man bør gjøre endringer.

Hva inneholder en ADR?

En ADR lagres som sagt i en markdownfil, typisk sammen med kildekoden. Man har gjerne én fil/ADR per avgjørelse. Det finnes ingen fast mal eller oppsett, men det finnes en del eksempler der ute og personlig har jeg typisk hatt følgende elementer med i en ADR.

Tittel: Kort beskrivelse av beslutningen.

Status: Er beslutningen godkjent, utprøvd, eller vurdert som en alternativ løsning?

Kontekst: Bakgrunnen for beslutningen – hva er problemet som må løses?

Beslutning: Hva ble valgt, og hvorfor?

Alternativer vurdert: Hvilke alternative løsninger ble vurdert, og hvorfor ble de forkastet?

Konsekvenser: Hvilke konsekvenser har beslutningen på systemet, teamet eller organisasjonen?

Referanser: Eventuelle lenker til relevant dokumentasjon eller eksterne ressurser.

Hvordan komme i gang?

Høres dette interessant ut? Da anbefaler jeg at du sjekker ut de relevante lenkene som ligger nederst i bloggposten for mer info om hva ADR er, hvorfor du bør ta det i bruk, samt en del eksempler på maler for å komme i gang.