8.4 Dokumentasjon og vedlikehold

Kode leses oftere enn den skrives

God dokumentasjon er nøkkelen til langsiktig vedlikehold. Kode leses langt oftere enn den skrives, og godt dokumentert kode gjør det enklere for andre – og for deg selv om seks måneder – å forstå hva som skjer. Det finnes flere nivåer av dokumentasjon.

Det første er kodekommentarer. Den viktigste regelen er at gode kommentarer forklarer hvorfor, ikke hva. En kommentar som x = x + 1 # Øk x med 1 er verdiløs, fordi den bare gjentar det åpenbare. En god kommentar forklarer hensikten: x = x + 1 # Kompenserer for null-indekserte arrays. Bruk kommentarer til kompleks logikk, midlertidige løsninger for kjente bugs, forklaring av forretningslogikk, og TODO-er. Bruk dem ikke som erstatning for god navngiving, til å forklare selvforklarende kode, eller til å beholde gammel, utdatert kode – den bør du heller slette.

Det andre nivået er docstrings, som dokumenterer funksjoner, klasser og moduler. I Python skrives de i trippel-anførselstegn rett under definisjonen, og bør beskrive hva funksjonen gjør, hvilke argumenter den tar, hva den returnerer, og gjerne et eksempel. En calculate_discount-funksjon kan ha en docstring som lister price, discount_percent og customer_tier med typer og forklaringer. Forskjellen er at kommentarer forklarer detaljer inni koden, mens docstrings beskriver grensesnittet utad – hvordan funksjonen skal brukes, uten at man trenger å lese implementasjonen.

God dokumentasjon i praksis

La oss se forskjellen på dårlig og god dokumentasjon side om side. En dårlig versjon kan se slik ut: def calc(a, b, c): med kommentaren «beregner noe», som ganger a * b og noen ganger multipliserer med 1.25. Problemene hoper seg opp: parameternavnene a, b, c sier ingenting, kommentaren er intetsigende, det finnes ingen docstring, og 1.25 er et «magisk tall» uten forklaring.

Den gode versjonen retter alt dette:

TAX_RATE = 1.25  # Moms 25%

def calculate_price(quantity, unit_price, include_tax):
    """
    Beregner totalpris for en bestilling.

    Args:
        quantity (int): Antall varer
        unit_price (float): Pris per vare i NOK
        include_tax (bool): Om moms skal inkluderes

    Returns:
        float: Totalpris i NOK
    """
    subtotal = quantity * unit_price
    if include_tax:
        return subtotal * TAX_RATE
    return subtotal

Legg merke til grepene. Funksjonsnavnet calculate_price er beskrivende. Parameternavnene forteller hva de er. Det magiske tallet 1.25 er gitt et navn, TAX_RATE, med en kommentar. Og en fyldig docstring beskriver argumenter og returverdi. Et tredje dokumentasjonsnivå er README-filer og teknisk dokumentasjon, som beskriver hele prosjektet: hva det gjør, hvordan man installerer og kjører det, og hvordan man bidrar. God dokumentasjon på alle disse nivåene er det som gjør et prosjekt mulig å vedlikeholde over tid – også for folk som aldri var med på å bygge det.

Teknisk gjeld og refaktorering

Når man tar snarveier for å rekke en frist – «vi rydder senere» – bygger man opp teknisk gjeld. Det er kompromisser i koden som gjør fremtidig utvikling vanskeligere, akkurat som økonomisk gjeld med renter: jo lenger du venter, jo dyrere blir det å betale tilbake. Teknisk gjeld viser seg gjerne som code smells – tegn på dårlig kode. Vanlige eksempler er altfor lange funksjoner som gjør for mye, duplisert kode som gjentas mange steder, dårlige navn, og dyp nesting av if-setninger.

Motgiften er refaktorering: å forbedre kodens struktur uten å endre hva den gjør. Tenk på en lang process_order-funksjon som validerer ordren, regner ut totalen, sjekker lageret og gir rabatt – alt i én klump på tjue linjer. Den er vanskelig å lese og teste. Ved refaktorering deler du den opp i mindre funksjoner med klare navn: valider_ordre, beregn_total, sjekk_lager, beregn_rabatt. Hver funksjon gjør én ting, blir lett å teste, og kan gjenbrukes. Resultatet er nøyaktig den samme oppførselen, men langt enklere å vedlikeholde.

To prinsipper hjelper deg å holde gjelden nede. «Boy Scout Rule» sier: forlat koden litt renere enn du fant den – rydd litt hver gang du er innom. Og husk at refaktorering er trygt nettopp når du har tester (fra forrige kapittel), fordi de fanger opp hvis du ved et uhell endrer oppførselen. Dokumentasjon, tester og refaktorering henger sammen: de er alle investeringer i at koden skal leve videre, lenge etter at den ble skrevet.

Oppsummering

Kode leses oftere enn den skrives, og dokumentasjon er nøkkelen til vedlikehold. Kommentarer skal forklare hvorfor, ikke hva, og docstrings beskriver grensesnittet til funksjoner, klasser og moduler. God kode bruker beskrivende navn, navngir magiske tall, og har en README som forklarer hele prosjektet.

Snarveier skaper teknisk gjeld, som viser seg som code smells – lange funksjoner, duplisering og dyp nesting. Motgiften er refaktorering: å forbedre strukturen uten å endre oppførselen, trygt fordi man har tester. Med «Boy Scout Rule» rydder man litt hver gang. I siste kapittel samler vi alt i et avsluttende prosjekt.