Gjenbruk i egen kode

Beste praksis

Besøk KVAKK-siden for å se på alle anbefalingene knyttet til kode og koding

🦆

KVAKK-gruppen har lagt ned arbeid i å samle beste praksis for gjenbruk. Dette er en del av et større arbeid for å samle beste praksis for arbeid i SSB.

I tillegg til KVAKKs side om gjenbruk, finnes det også en side om beste praksis ved gjenbruk i egen kode og en side om SonarCloud - et verktøy for å finne kodefeil og sikkerhetsproblemer i koden.

Klikk på lenkene for å lese mer.

Gjenbruk i egen kode

1. 🚨 Gjenbruk kan redusere feil

   Kode skrevet i henhold til beste praksis skal testes og fungere som forventet. Ved å gjenbruke kode som er testet og fungerer, kan du redusere risikoen for feil.

2. 🚀 Gjenbruk kan øke produktiviteten

   Gjenbruk kan redusere utviklingstid, og fordi ⌛ == 💰 kan man oppnå reduserte kostnader

3. 🦆 Gjenbruk kan øke kvaliteten på koden

   Har du en funksjon som fungerte bra i et tidligere prosjekt? Hvorfor ikke utvide og bruke den igjen?

4. 🧩 Gjenbruk kan redusere kompleksitet

   Ved å bryte ned store oppgaver i mindre deler, dokumentere bestandelene, og sette de logisk sammen igjen, er koden mer oversiktlig for deg og dine kjære kolleger.

Ti punkter om gjenbruk i egen kode

1. Oppdeling
2. Bruk beskrivende navn
3. Gjør funksjoner generiske der det er hensiktsmessig
4. Dokumentasjon
5. Parameterisering

6. Unngå sideeffekter
7. Enhetstesting
8. Dekomponering av store oppgaver
9. Modulorganisering
10. Bruk av __init__.py

11. Standardisering

1. Oppdeling - Del opp koden i logisk sammenhengende funksjoner. Hver funksjon bør utføre en bestemt oppgave eller ha et bestemt ansvarsområde. Dette gjør koden enklere å forstå og vedlikeholde.

2. Bruk beskrivende navn - Gi funksjoner (og variabler) beskrivende navn som tydelig indikerer hva de gjør. Dette gjør koden mer selvforklarende og hjelper andre med å forstå hensikten til funksjonen.

3. Gjør funksjoner generiske der det hensiktsmessig - Lag generiske funksjoner der det er hensiktsmessig. Ikke bruk hardkodede verdier og avhengigheter som begrenser bruken av funksjonen. Dette gjør funksjonen mer gjenbrukbar i ulike kontekster.

4. Dokumentasjon - Legg til kommentarer og dokumentasjon i funksjoner for å forklare hvordan de skal brukes, hvilke argumenter de tar imot, og hva de returnerer. Dette hjelper andre utviklere og deg selv med å bruke funksjonene riktig.

5. Parameterisering - Tillat funksjoner å være parametriske ved å ta inn argumenter. Dette gjør det mulig å tilpasse funksjonenes atferd ved å endre inndata.

6. Unngå sideeffekter - Unngå sideeffekter i funksjoner, dvs. endringer i globale tilstander eller variabler utenfor funksjonens omfang. Dette bidrar til å gjøre funksjoner mer forutsigbare og testbare.

7. Enhetstesting - Lag enhetstester for funksjonene dine. Dette sikrer at de fungerer som forventet, og at endringer i koden ikke introduserer feil.

8. Dekomponering av store oppgaver - Hvis en funksjon blir for stor eller kompleks, bør du vurdere å dele den opp i mindre funksjoner. Dette bidrar til å forbedre lesbarheten og vedlikeholdbarheten.

9. Modulorganisering - Organiser relaterte funksjoner i moduler/filer og pakk dem i kataloger etter behov. Dette gir en strukturert tilnærming til gjenbruk av kode.

10. Bruk av init.py - Hvis du lager en mappe for en pakke med flere moduler, må du inkludere en init.py-fil i mappen. Dette gjør mappen til en pakke som kan importeres som en enhet.

prog/mjauvoff.py

def dyr(*dyr):
    for i in dyr:
        if i == 'katt':
            print('Mjau')
        elif i == 'hund':
            print('VOF')
        else:
            print(f"{i} sier hverken mjau eller vof")

dyr("gorilla", "katt", "hund", "elefant")

bash

.
├── prog/
│   └── mjauvoff.py
├── pyproject.toml
└── README.md

Caution

Slidene er gjenstand for grov overforenkling og inneholder definitivt feil.

Forelesningen forutsetter at du har kjennskap til noe grunnleggende Python og er kjent med Linux og dets filsystem.

I kolonnen til høyre ser du en enkel Python-funksjon som tar inn en vilkårlig mengde argumenter og printer ut en lyd avhengig av hva slags dyr det er. Grunnleggende Python kommandoer vil si at man kjenner til funksjoner, løkker og betingelser.

I kolonnen til venstre er en enkel mappestruktur for et Python-prosjekt. . markerer at vi er i rotmappen i arbeidsområdet. Under src ligger Python-koden, mens notebooks inneholder Jupyter Notebooks. pyproject.toml er en konfigurasjonsfil for prosjektet, mens README.md er en beskrivelse av prosjektet som vises på GitHub.

En liten disclaimer er at undertegnede ikke har jobbet på Dapla, har ikke deployet noen applikasjoner, og kan ha mottatt noe vranglære fra en eller annen video på YouTube.

1. Prinsippløs koding

“Ukentlig planlegging av vaffelfester er viktig for SSB. Vi har derfor laget et program som leser inn en CSV-fil med gjester, beregner hvor mye ingredienser som trengs og skriver ut en handleliste.”

hele_sullamitten.py

import csv

data = []
with open('$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024/g2024m03d14_lag42.csv') as fil:
    fil_2 = csv.reader(fil, delimiter=',')
    for rad in fil_2:
        data.append(rad)
        
count = len(mydata)

import datetime 

hvete, egg, melk = 0.4 * count, 3 * count 0.4 * count

with open("$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024/handleliste.csv", "w") as fil:
    fil2 = csv.writer(fil)
    fil2.writerow(["dato", "hvetemel", "egg", "melk"])
    fil2.writerow([datetime.datetime.now(), hvetemel, egg, melk])

Legger man godvilja til er dette sannsynligvis noe man kan ha sett i SAS. Med “prinsippløs koding” mener jeg her at koden er skrevet uten tanke på struktur, gjenbruk og lesbarhet. Koden er skrevet som en enkel skriptfil som gjør alt på en gang. Dette er en vanlig måte å skrive enkle programmer på, og er ikke noe galt i seg selv for læring og prototyping, men er vanskelig å sette seg inn i.

2. Logisk struktur og variabelnavn

hele_sullamitten.py

import csv
import datetime 

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

gjesteliste = []
with open(INNFIL) as infil:
    infil_gjesteliste = csv.reader(infil, delimiter=',')
    for gjest in infil_gjesteliste:
        gjesteliste.append(gjest)

antall_gjester = len(gjesteliste)

# Beregner ingredienser
hvete, egg, melk = 0.4 * antall_gjester, 3 * antall_gjester 0.4 * antall_gjester

with open(UTFIL, "w") as utfil:
    utfil_handleliste = csv.writer(utfil)
    utfil_handleliste.writerow(["dato", "hvetemel", "egg", "melk"])
    utfil_handleliste.writerow([datetime.datetime.now(), hvetemel, egg, melk])

I dette eksempelet har vi gitt variablene og funksjonene mer beskrivende navn. Importer er flyttet til toppen av filen, og vi har definert noen konstanter som vi kan gjenbruke.

3: Oppdeling i funksjoner

hele_sullamitten.py

import csv
import datetime 

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

def les_csv_fra_vaffelregisteret():
    data = []
    with open(INNFIL) as fil:
        fil2 = csv.reader(fil, delimiter=',')
        for rad in fil2:
            data.append(rad)

    return data

def beregn_ingredienser():
    antall_gjester = len(vaffelfil)
    hvete, egg, melk = 0.4 * antall_gjester, 3 * antall_gjester, 0.4 * antall_gjester
    return hvete, egg, melk

def skriv_til_csv():
    with open(UTFIL, "w") as utfil:
        utfil_handleliste = csv.writer(utfil)
        utfil_handleliste.writerow(["dato", "hvetemel", "egg", "melk"])
        utfil_handleliste.writerow([datetime.datetime.now(), hvetemel, egg, melk])

def main():
    vaffelfil = les_csv_fra_vaffelregisteret()
    hvetemel, egg, melk = beregn_ingredienser()
    skriv_til_csv()

Vi kan gjøre enda bedre ved å skille ut oppgavene i egne funksjoner. Dette gjør koden mer modulær hvor vi har oversikt over hver funksjon som har en spesifikk oppgave. Vi har også lagt til en main-funksjon som koordinerer de andre funksjonene.

Dette er tiden for å begynne å tenke på å strukturere koden i moduler.

4. Skille ut i moduler

vaffelprosjekt/hele_sullamitten.py

import csv
import datetime 

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

def les_csv():
    ...

def beregn_ingredienser():
    ...

def skriv_til_csv():
    ...

def main():
    ...

main()

Linux

/vaffelprosjekt/
├── hele_sullamitten.py
└── pyproject.toml

I kolonnen til venstre er Python-koden oppsummert, mens høyre kolonne viser en enkel mappestruktur for prosjektet. Vi har en enkelt Python-fil og en konfigurasjonsfil for prosjektet. Hele programmet kjøres fra hele_sullamitten.py.

4. Skille ut i moduler

vaffelprosjekt/main.py

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

def main():
    ...

main()

Linux

/vaffelprosjekt/
├── main.py
├── funksjoner/
│   ├── __init__.py
│   ├── les_csv.py
│   ├── beregn_ingredienser.py
│   └── skriv_til_csv.py
└── pyproject.toml

Her har jeg skilt ut funksjonene i egne moduler: * main.py: Hovedfilen som koordinerer de andre funksjonene * funksjoner/: En mappe med moduler for de andre funksjonene * init.py: En tom fil som markerer mappen som en Python-pakke * les_csv.py: Modul for å lese inn CSV-fil * beregn_ingredienser.py: Modul for å beregne ingredienser * skriv_til_csv.py: Modul for å skrive til CSV-fil * pyproject.toml: Konfigurasjonsfil for prosjektet

4. Skille ut i moduler

from funksjoner import les_csv, beregn_ingredienser, skriv_til_csv

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

def main():
    vaffelfil = les_csv_fra_vaffelregisteret()
    hvetemel, egg, melk = beregn_ingredienser()
    skriv_til_csv()

main()

Linux

/vaffelprosjekt/
├── program.py
├── funksjoner/
│   ├── __init__.py
│   ├── les_fil.py
│   ├── beregn_ingredienser.py
│   └── skriv_fil.py
└── pyproject.toml

Ved å importere funksjonene fra funksjoner-mappen kan vi nå bruke dem i main-funksjonen. Dette gjør det mer oversiktlig, og gjemmer unødvendige detaljer fra brukeren av funksjonene.

5. Parameterisering

funksjoner/beregn_ingredienser.py

def beregn_ingredienser():
    antall_gjester = len(vaffelfil)
    hvete, egg, melk = 0.4 * antall_gjester, 3 * antall_gjester, 0.4 * antall_gjester
    return hvete, egg, melk

For å korte oss i fatthet kan vi se spesifikt på en funksjon. beregn_ingredienser-funksjonen gir oss som nevnt tre variabler

5. Parameterisering

funksjoner/beregn_ingredienser.py

def beregn_ingredienser(vaffelfil):
    antall_gjester = len(vaffelfil)
    hvete, egg, melk = 0.4 * antall_gjester, 3 * antall_gjester, 0.4 * antall_gjester
    return hvete, egg, melk

Hvis vi fokuserer på beregn_ingredienser-funksjonen ser vi at den er avhengig av en variabel vaffelfil som ikke er definert i funksjonen. Vi kan gjøre funksjonen mer generell ved å sende inn vaffelfil som et argument.

5. Parameterisering

funksjoner/beregn_ingredienser.py

def beregn_ingredienser(vaffelfil, oppskrift = {
    "hvete": 0.4,
    "egg": 3,
    "melk": 0.4,
}):
    handleliste = {}
    antall_gjester = len(vaffelfil)
    for ingrediens, mengde in oppskrift.items():
        handleliste[ingrediens] = mengde * antall_gjester
    
    return handleliste

Vi kan også legge til en “oppskrift” som et valgfritt argument med en standardverdi. Her implementeres dette som en dictionary der hver ingrediens er en nøkkel og mengden er verdien. Dette gjør det enkelt å endre oppskriften uten å endre koden. I stedet for å hardkode oppskriften i funksjonen, kan vi sende inn oppskriften som et argument og iterere over den. Og i stedet for å returnere tre variabler, kan vi returnere en dictionary med ingrediensene og mengdene.

6. Dokumentasjon

funksjoner/beregn_ingredienser.py

def beregn_ingredienser(vaffelfil, oppskrift = {
    "hvete": 0.4,
    "egg": 3,
    "melk": 0.4,
}):
    """
    Beregner mengde ingredienser ut fra en oppskrift og antall gjester.
    @param vaffelfil: En liste med gjester (list)
    @param oppskrift: En oppskrift på vaffelrøre (dict)
    """
    handleliste = {}
    antall_gjester = len(vaffelfil)
    for ingrediens, mengde in oppskrift.items():
        handleliste[ingrediens] = mengde * antall_gjester

    return handleliste

En funksjon bør også ha en beskrivelse av hva den gjør, hvilke parametre den tar inn og hva den returnerer. Dette kan gjøres med en såkalt docstring, som er en streng som står øverst i funksjonen.

6. Dokumentasjon

funksjoner/beregn_ingredienser.py

def beregn_ingredienser(vaffelfil: list, oppskrift: dict = {
    "hvete": 0.4,
    "egg": 3,
    "melk": 0.4,
}) -> dict:
    """
    Beregner mengde ingredienser ut fra en oppskrift og antall gjester.
    """
    handleliste = {}
    antall_gjester: int = len(vaffelfil)
    for ingrediens, mengde in oppskrift.items():
        handleliste[ingrediens] = mengde * antall_gjester
    
    return handleliste

Et alternativ eller supplement til docstrings er å bruke typehinting. Dette er en måte å angi hvilken type data en funksjon tar inn og returnerer. Dette er spesielt nyttig i store prosjekter der det kan være vanskelig å holde oversikt over hva slags data som sendes inn og ut av funksjoner.

Vellykket vaffelfunksjon

from funksjoner import les_csv, beregn_ingredienser, skriv_til_csv

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

def main():
    vaffelfil = les_csv(infil=INNFIL)
    handleliste = beregn_ingredienser(vaffelfil=vaffelfil, oppskrift={
        "glutenfritt mel": 0.4,
        "egg": 3,
        "melk": 0.4,
    })
    skriv_til_csv(utfil=UTFIL, handleliste=handleliste, som_ordbok=True)

main()

Linux

/vaffelprosjekt/
├── main.py
├── funksjoner/
│   ├── __init__.py
│   ├── les_fil.py
│   ├── beregn_ingredienser.py
│   └── skriv_fil.py
└── pyproject.toml

Summa summarum har vi nå en oversiktlig mappestruktur og en oversiktlig hovedfil. Vi har skilt ut funksjonene i egne moduler, og vi har parameterisert funksjonene slik at de er mer generelle og gjenbrukbare. Vi har også lagt til dokumentasjon og typehinting for å gjøre koden mer lesbar og forståelig. Vi har også lagt til en valgfri oppskrift slik at også cøliakiere kan feire vaffeldagen.

Vellykket vaffelfunksjon

from funksjoner import les_csv, beregn_ingredienser, skriv_til_csv

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

def main():
    vaffelfil = les_csv(infil=INNFIL)
    handleliste = beregn_ingredienser(vaffelfil=vaffelfil, oppskrift={
        "glutenfritt mel": 0.4,
        "egg": 3,
        "melk": 0.4,
    })
    skriv_til_csv(utfil=UTFIL, handleliste=handleliste, som_ordbok=True)

main()

Linux

/vaffelprosjekt/
├── main.py
├── funksjoner/
│   ├── __init__.py
│   ├── les_fil.py
│   ├── beregn_ingredienser.py
│   └── skriv_fil.py
└── pyproject.toml

Tester?

from funksjoner import les_csv, beregn_ingredienser, skriv_til_csv

FILSTI = f"$VAFFELREGISTERET/a300/statistikkfil/wk48/vaffelfester/g2024"
INNFIL = f"{FILSTI}/g2024m03d14_lag42.csv"
UTFIL = f"{FILSTI}/handleliste.csv"

def main():
    vaffelfil = les_csv(infil=INNFIL)
    handleliste = beregn_ingredienser(vaffelfil=vaffelfil, oppskrift={
        "glutenfritt mel": 0.4,
        "egg": 3,
        "melk": 0.4,
    })
    skriv_til_csv(utfil=UTFIL, handleliste=handleliste, som_ordbok=True)

main()

Linux

/vaffelprosjekt/
├── main.py
├── funksjoner/
│   ├── __init__.py
│   ├── les_fil.py
│   ├── beregn_ingredienser.py
│   └── skriv_fil.py
├── tests/
│   ├── __init__.py
│   ├── test_les_fil.py
│   ├── test_beregn_ingredienser.py
│   └── test_skriv_fil.py
├── README.md/
└── pyproject.toml

Når vi har en funksjon som fungerer som den skal, kan vi skrive tester for å sjekke at funksjonen oppfører seg som forventet. Dette gjør det enklere å finne feil og endre koden uten å ødelegge noe som allerede fungerer. Jeg skal ikke gå inn på noen eksakte eksempler på tester nå, men det er viktig å bli nevnt.

Annet?

• Generisk funksjonalitet
• SonarCloud code review
• Beste praksis fra funksjonell og objektorientert programmering

Jo mer man lærer, jo mer vet man

Linux

/vaffelprosjekt/
├── main.py
├── funksjoner/
│   ├── __init__.py
│   ├── les_fil.py
│   ├── beregn_ingredienser.py
│   └── skriv_fil.py
├── tests/
│   ├── __init__.py
│   ├── test_les_fil.py
│   ├── test_beregn_ingredienser.py
│   └── test_skriv_fil.py
├── README.md/
└── pyproject.toml

Andre ting som kan være nyttig å nevne er generisk funksjonalitet, SonarCloud kodeverktøy, og beste praksis fra funksjonell og objektorientert programmering. Med andre ord, god praksis for koding øker med erfaring og kunnskap. Det kan f.eks. være nyttig å lære både R og Python for å få et bredere perspektiv på programmering.

Takk for meg!