5 grep som gjør det enklere å overta koden din

Overlevering av kode, enten fordi noen slutter eller fordi et nytt forvaltningsteam skal overta, koster skjorta. Da snakker jeg ikke Zara-skjorter, men snarere av typen håndvevet bunadsskjorte i egyptisk bomull. Grunnen til dette er at nye utviklere eller team trenger tid til å sette seg skikkelig inn i logikk, arkitektur, tankesett og problemstillinger som ligger bak kodene.

Selv om tekniske ledere og arkitekter ofte har hovedansvaret for systemdokumentasjon, må alle i teamet bidra på egne fagområder slik at det de skaper er forståelig og håndterbart for andre. Her er 5 prinsipper som jeg selv har satt pris på at forfatteren av koden jeg skal overta har fulgt:

1. Velg gode og uttrykksfulle navn

God navngivning er viktig for forståelse av kode. Ekspressiv kode er et stort tema som ikke ytes rettferdighet i én artikkel, men ved å dra veksel på utvalgte prinsipper kan du gjøre det enklere for andre å lese koden din:

Skriv fulle setninger fremfor forkortelser:

const usrAToken vs const usersCurrentAuthToken

Bruk verb som beskriver HVA og HVORDAN:

bookList() vs getBookListFromLocalAsync()

Ikke vær redd for lange navn, innen rimelighetens grenser. Selv synes jeg det er lettere å forholde meg til lange funksjonsnavn enn forkortelser som enkelte ganger kan være til forveksling like:

fsRBookList() vs fsWBookList()

2. Forklar hvorfor koden gjør det den gjør

Begrepet “selvdokumenterende kode” antyder at koden i seg selv er så godt navngitt og organisert at man forstår den uten videre kommentarer. Allikevel — kommentarer handler ikke nødvendigvis om hva koden gjør der og da, men vel så viktig HVORFOR, og gjerne også med et par ord om hvordan utvikleren har resonnert da hun krev koden.

Ikke forklar HVA koden din gjør, men HVORFOR den gjør det.

Eksemplene nedenfor viser hvordan intetsigende kommentarer (første blokk) kan forbedres ved å forklare HVORFOR utvikleren har tatt de valgene hun har tatt (andre blokk).

3. Komprimert kode er ikke alltid best

Det ligger yrkesstolthet i å refaktorere 4 kodelinjer ned til én, og jeg skal innrømme at det gir en godfølelse i å returnere en kompleks énlinjer uten å søle en eneste deklarasjon i funksjonen.

Dog — finurlig og elegant kode er imponerende der og da, men på sikt vanskelig å både vedlikeholde og forstå. Hvor mange av oss har ikke skrevet komplekse énlinjere, for så 3 måneder senere å slite med å forstå samme kode?

Eksempelet ovenfor er selvsagt satt på spissen og med en lite effektiv grenseutregning av dato, men poenget her er vanskelig lesbare énlinjere..

Ved å tillate seg litt pusterom i form av noen ekstra deklarasjoner underveis blir koden lettere å lese. I dette eksempelet er det lite trolig at ytelsen i klienten faller nevneverdig, med mindre det er snakk om store mengder data som skal traverseres:

Eksempelet viser hvordan kode med litt mer pusterom i form av deklarasjoner underveis gjør hele blokken lettere å lese.

4. Prøv å formidle arkitekturen i koden

De fleste rammeverk og biblioteker har en form for “beste praksis” når det gjelder arkitektur og organisering. Allikevel har mange prosjekter litt ulik strategi med hensyn til feks. organisering av filer, og bootstrapping av oppstartslogikk eller lagring av data.

Derfor er det viktig å kunne gi et overblikk over applikasjonen og de grunnleggende tankene og valgene som teamet har gjort:

• Hvor skjer programkritisk oppstart og bootstrapping?
• Hvor lastes de aller første dataene inn?
• Er det noen spesiell grunn til at data lastes på dette tidspunktet i oppstart?
• Hvilke moduler har ansvar for API-kall?
• Hvilke views er de mest sentrale i applikasjonens oppstart?

Slike veivisere gjør at nye utviklere lettere kan finne frem til konkrete deler av koden og skaffe seg et bedre bilde av strukturen på egenhånd.

Se på det som en slags “hjelp til selvhjelp”. Du ønsker å gi leseren, altså utvikleren, gode anvisninger av hvor i koden de finner svar på spørsmål uten at du skriver så kompleks dokumentasjon at den er råtten og utdatert i løpet av kun et par sprinter.

5. Hold kodenær dokumentasjon i repo

Systemdokumentasjon og arkitektur skal selvsagt håndteres og lagres i egnede plattformer som for eksempel Confluence. Problemet oppstår når systemet videreutvikles, og avviket mellom dokumentasjon og kodebase blir for stort. Det skjer ofte når disse er plassert for langt fra hverandre, på forskjellige plattformer.

Dokumentasjon som er tett plassert sammen med kode, har større sjanse for å bli oppdatert parallelt med videreutvikling av løsningen.

Derfor kan det være en god idé å legge readme.md i kodebasen slik at den er lett tilgjengelig for utvikleren som både skal lese seg opp og senere forvalte og videreutvikle.

Lesbar kode, linje for linje, er én ting. En god totalforståelse noe helt annet. Iblant ser jeg for meg at jeg koder for et publikum, noe jeg forsåvidt gjør siden repoet ligger public på GitHub, og bare dét gjør at jeg retter meg litt i ryggen og tenker meg om et par ganger før jeg committer:

• Er dette god navngivning?
• Er koden selvforklarende nok, eller burde jeg koste på meg et par linjer med kommentarer?
• Forsøkt sett utenifra: Hvordan ville jeg ha forstått denne koden dersom andre hadde skrevet den?

Det er selvsagt ingen absolutte svar, men en holdning til at andre en dag skal måtte forholde seg til koden vi skriver. Sammen med de 5 tommelfingerreglene ovenfor er dette et solid bidrag i det daglige til at prosjektet som helhet blir lettere å sette seg inn i for de som skal jobbe med koden etter deg.

I utgangspunktet er det en fordel å unngå en slik overlevering og heller legge opp til at teamet følger produktet — også inn i forvaltning. Utskiftning av mennesker eller team i et prosjekt er allikevel uungåelig, og denne artikkelen handler om hvordan vi som utviklere kan legge tilrette for at de som kommer etter oss raskere kan sette seg inn i koden vi har skrevet.

Anbefalt lesning:

• “Clean Code, A book of agile software craftmanship” av Robert C Martin.
• “The Pragmatic Programmer” av Andrew Hunt.
• “Hvordan gjør du mottaksprosjekter smidigere?” av Knut Nymoen