Att dokumentera lösningar

Visualisera dina lösningar

På konferensen i Edinburgh körde vi i kompetensområde Java en presentation om hur vi kan dokumentera våra lösningar. Just dokumentation är något vi diskuterat en del den senaste tiden eftersom det känns som att dokumentation ofta hamnar i skymundan.

Att efterfråga dokumentation gör inte sällan att det knorras en del om att koden dokumenterar sig själv, att inte dokumentera för mycket, att dokumentation inte underhålls och därmed snabbt förlorar i aktualitet. Ett sånt resonemang leder till att vi reducerar värdet i det vi producerar till att enbart gälla fungerande kod. Men fungerande kod utan dokumentation riskerar i förlängningen att förlora sin idé vad gäller arkitektur och design. Kontentan blir att koden då ökar i komplexitet och blir svårare att förändra.

Det agila manifestet menar visserligen att vi ska prioritera fungerande kod framför omfattande dokumentation, men ibland känns som om vi blivit så agila att vi inte tar oss den tid vi behöver för att dokumentera både våra krav och lösningar ordentligt. Alltför ofta stöter vi på krav som skapar fler frågor än svar, bristfällig dokumentation, eller ingen dokumentation alls, om de system vi ska förändra och bygga vidare på.

Varför vi dokumenterar

Att dokumentera är att kommunicera. Att kommunicera till de personer som kommer efter, vad vi har byggt och varför. Vi vill kommunicera själva idén om hur vår lösning är genomförd för att vara säkra på att arkitekturen bibehålls även när ett annat team tar över. Lyckas vi med det kommer morgondagens utvecklare, kanske vi själva, ha större möjligheter att bättre förvalta den applikation vi byggt. Applikationens möjlighet att leva längre ökar.

C4-modellen

En modell att följa vid dokumentation som vi kikat närmare på inom javagänget är något som kallas C4, där de 4 C:na står för context, container (inte docker), components, och code. Tanken är att visualisera applikationen i 4 olika detaljnivåer och att man i princip skapar en berättelse genom de olika diagrammen. Första diagrammet med applikationen placerat i sin kontext för att sedan fördjupa den tekniska detaljrikedomen i de efterföljande diagrammen för containers, komponenter och kod.

System Context – utgångspunkten för att snabbt förstå “the big picture”. Alltså vem eller vilka som använder en applikation och dess huvudsakliga beroenden till andra applikationer. Målet är att visa applikationen i sin kontext. Här finns inte tekniska detaljer som protokoll och dataformat med, vilket gör att vi kan diskutera diagrammet med personer med annat fokus än teknik.

Containers – här öppnas applikationen upp för att se vad den består av. De olika delarna kallas containers och kan vara till exempel webbappar, mobilappar, databaser eller filsystem. Här vill man även få med teknikval som till exempel språkval, ramverk, och hur komponenterna kommunicerar med varandra som till exempel json, https, jdbc, smtp.

Component – här zoomas in på en specifik container för att visa de komponenter som finns i den. Det räcker ofta med att ta med de viktigaste komponenterna. T ex hur spring controllers använder andra komponenter för inloggning eller för att skicka email. Det här diagrammet bör även reflektera den struktur som finns i kod-repot.

Code – specifika diagram för att beskriva kod i en komponent såsom klassdiagram eller sekvensdiagram. Viktigt dock att man inte överarbetar detaljnivån på denna nivå eftersom utvecklare kan få tag i detaljerna i koden

Jag gillar den här ansatsen att skapa strukturer i sin dokumentation och är du nyfiken på att läsa mer så gör en sökning på C4 model.

Vid pennan/ Stefan Nildén, CAG Contactor