Kommentarer och dokumentation i Python

Att skriva kod som fungerar är viktigt – men det är minst lika viktigt att andra (eller du själv om ett halvår) kan förstå vad koden gör. Därför kommenterar vi vår kod och dokumenterar funktioner och klasser.

Vad är en kommentar?

En kommentar är text som inte körs av datorn, utan används för att förklara vad koden gör.

Man skriver en kommentar med #:

# Detta är en kommentar
namn = input("Vad heter du?")  # Här läser vi in namn från användaren

När ska man kommentera?

• När du gör något som inte är självklart
• När du använder ett trick eller ett ovanligt sätt att lösa något
• När du skriver en funktion – skriv vad den gör
• När koden är svår att förstå direkt

Kommentarer ska INTE…

• …förklara varje enskild rad i enkel kod
• …upprepa det som redan är tydligt

Dåligt exempel:

x = 5  # x är lika med 5

Dokumentation med docstrings

När du skriver egna funktioner eller klasser är det bra att använda docstrings – särskilda kommentarer inuti tre citattecken (""").

De ska kort beskriva vad funktionen gör, vilka argument den tar och vad den returnerar (om något).

def beräkna_area(bredd, höjd):
    """
    Beräknar arean av en rektangel.
    Argument:
        bredd – rektangelns bredd (float)
        höjd – rektangelns höjd (float)
    Returnerar:
        float – arean
    """
    return bredd * höjd

Docstrings kan visas automatiskt i vissa utvecklingsmiljöer (t.ex. VS Code) och används i hjälpverktyg som help().

Sammanfattning