Teknisk gæld som forretningsbeslutning — sådan dokumenterer du arkitekturvalg med ADR'er

"Teknisk gæld" er blevet et ord, udviklere bruger, når noget er rodet, og som ledelsen hører som en undskyldning. Det er synd, for metaforen er præcis, og den er skabt til netop den samtale. Ward Cunningham introducerede den i 1992 for at forklare forretningen, hvorfor kode skal omskrives, efterhånden som man lærer mere: man låner tid nu og betaler tilbage senere, med renter.

Dette indlæg handler om at behandle teknisk gæld som det, den er, nemlig en forretningsbeslutning, og om et let værktøj til at dokumentere den: Architecture Decision Records. Eksemplet bruger den fiktive virksomhed Space Travel.

Gæld er et valg, der har en rente

Gæld er ikke i sig selv dårlig. Et lån kan være den bedste beslutning, en virksomhed træffer, hvis det giver mulighed for noget, der ellers ikke kunne lade sig gøre. Det samme gælder kode. At udgive en enklere løsning før en messe, en lancering eller en konkurrent kan være præcis det rigtige.

Problemet er gæld, ingen ved, de har optaget. Martin Fowler har beskrevet forskellen med to akser: er gælden bevidst eller ubevidst, og er den forsigtig eller hensynsløs? Bevidst, forsigtig gæld lyder sådan: "Vi udgiver nu og ved, hvad det koster at rydde op." Ubevidst gæld opdager man først, når renten allerede er betalt i form af langsommere udvikling, flere fejl og udviklere, der ikke tør røre bestemte dele af koden.

Renten er det, der gør gæld til et forretningsspørgsmål. Hver gang nogen skal ændre den del af systemet, koster det ekstra tid. Jo oftere den del ændres, jo højere rente. Gæld i kode, der aldrig røres, koster næsten intet. Gæld i kernen af produktet koster hver uge.

Architecture Decision Records

En Architecture Decision Record, en ADR, er et kort dokument om én vigtig beslutning. Formatet blev gjort populært af Michael Nygard i 2011 og består typisk af:

• Titel og nummer, så beslutningen kan refereres.
• Status: foreslået, accepteret, erstattet af en senere ADR.
• Kontekst: situationen og kræfterne, der trækker i hver sin retning. Det er den vigtigste del, og den, man oftest glemmer.
• Beslutning: hvad vi gør, skrevet aktivt.
• Konsekvenser: hvad der bliver lettere, hvad der bliver sværere, og hvilken gæld vi bevidst optager.

ADR'er ligger bedst i repositoryet, f.eks. i docs/architecture/adr/, ved siden af koden de handler om. De gennemgås i samme pull request som ændringen, og de rettes ikke bagefter: ændres beslutningen, skrives en ny ADR, der erstatter den gamle. Så viser historikken både, hvad der blev besluttet, og hvorfor det engang gav mening.

En skabelon kan være så enkel som denne:

Gæld skrevet ned som en ADR

Når en beslutning bevidst optager gæld, skal ADR'en sige det højt: hvad udskydes, hvad koster det, og hvornår skal det betales tilbage. Space Travel vil lancere online booking før sæsonstart, men den fulde integration med økonomisystemet vil tage for lang tid. Teamet vælger at fakturere manuelt i første version:

Det vigtigste i eksemplet er ikke formuleringerne, men at tilbagebetalingen har en udløser: et konkret tal, der gør det klart, hvornår renten er blevet for høj. Uden en udløser bliver "midlertidigt" til "permanent", fordi der altid er noget mere presserende.

Hvornår skal man skrive en ADR?

Ikke hver beslutning fortjener et dokument. En god test er at spørge: vil en ny kollega om et år undre sig over, hvorfor det er sådan? Typiske kandidater er valg af database, framework eller hostingmodel, grænser mellem systemer, sikkerhedsmodellen, og alle beslutninger, der bevidst optager gæld.

Hold dem korte. En ADR på én side bliver læst; en på ti sider bliver det ikke. Skriv den, mens beslutningen træffes, ikke bagefter, for det er konteksten, man glemmer først. Og skriv også de muligheder ned, man valgte fra, med én linje om hvorfor. Det sparer den samme diskussion, næste gang nogen foreslår dem.

Samtalen med forretningen

Udviklere og forretning taler ofte forbi hinanden om gæld. "Vi skal refaktorere" lyder som en omkostning uden gevinst. Det hjælper at oversætte til de begreber, forretningen allerede bruger:

• Hovedstol: hvad koster det at rydde op? Et estimat i dage eller sprints.
• Rente: hvad koster gælden løbende? Ekstra tid pr. ændring, fejl i produktion, manuelt arbejde, oplæring.
• Løbetid: hvor længe kan vi leve med den, og hvad sker der, hvis vi venter?

Med de tre tal bliver beslutningen sammenlignelig med andre investeringer. Nogle gange er svaret at leve med gælden, fordi koden sjældent ændres. Andre gange er det billigere at betale nu end at fortsætte med at betale renter. Begge svar er gode, så længe de er bevidste og skrevet ned.

En god vane er at gennemgå de åbne gælds-ADR'er med jævne mellemrum, f.eks. hvert kvartal: er udløserne nået, er renten steget, og er der ny gæld, der burde være skrevet ned?