Kommentarer er noter, som programmører tilføjer til deres kode for at forklare, hvad det er meningen, at koden skal gøre. De compilere eller fortolkere, der omsætter kode til handling, ignorerer kommentarer, men de kan være vigtige for forvaltningen af softwareprojekter.

Kommentarer er med til at forklare din Python-kode for andre programmører og kan minde dig om, hvorfor du har truffet de valg, du har gjort. Kommentarer gør debugging og revision af kode nemmere ved at hjælpe fremtidige programmører med at forstå de designvalg, der ligger bag softwaren.

Selv om kommentarer primært er for udviklere, kan det at skrive effektive kommentarer også hjælpe med at producere fremragende dokumentation til brugerne af din kode. Ved hjælp af dokumentgeneratorer som Sphinx for Python-projekter kan kommentarer i din kode give indhold til din dokumentation.

Lad os kigge nærmere på kommentering i Python.

Kommentarer i Python

Ifølge PEP 8 Style Guide for Python er der flere ting, som man skal være opmærksom på, når man skriver kommentarer:

  • Kommentarer skal altid være fuldstændige og kortfattede sætninger.
  • Det er bedre slet ikke at have nogen kommentar end at have en kommentar, der er svær at forstå eller upræcis.
  • Kommentarer bør opdateres regelmæssigt for at afspejle ændringer i din kode.
  • For mange kommentarer kan være distraherende og forringe kodekvaliteten. Kommentarer er ikke nødvendige, når kodens formål er indlysende.

I Python er en linje erklæret som en kommentar, når den begynder med symbolet #. Når Python-fortolkeren støder på # i din kode, ignorerer den alt efter dette symbol og producerer ikke nogen fejl. Der er to måder at deklarere kommentarer på én linje på: inline kommentarer og blokkommentarer.

Inline-kommentarer

Inline-kommentarer giver korte beskrivelser af variabler og simple operationer og skrives på samme linje som kodeangivelsen:

border = x + 10  # Make offset of 10px

Kommentaren forklarer kodens funktion i samme udsagn som koden.

Blokkommentarer

Blokkommentarer bruges til at beskrive kompleks logik i koden. Blokkommentarer i Python er opbygget på samme måde som inline-kommentarer – den eneste forskel er, at blokkommentarer skrives på en separat linje:

import csv
from itertools import groupby

# Get a list of names in a sequence from the csv file
with open('new-top-firstNames.csv') as f:
    file_csv = csv.reader(f)

# Skip the header part: (sr, name, perc)
header = next(file_csv)
    
# Only name from (number, name, perc)
persons = [ x[1] for x in file_csv]

# Sort the list by first letter because 
# The groupby function looks for sequential data.
persons.sort(key=lambda x:x[0])
data = groupby(persons, key=lambda x:x[0])

# Get every name as a list 
data_grouped = {}
for k, v in data:
    # Get data in the form 
    # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]}
    data_grouped[k] = list(v)

Bemærk, at når du bruger blokkommentarer, skrives kommentarerne over den kode, som de forklarer. Python PEP8 Style Guide dikterer, at en kodelinje ikke bør indeholde mere end nioghalvfjerds tegn, og inline-kommentarer skubber ofte linjerne over denne længde. Derfor skrives blokkommentarer for at beskrive koden på separate linjer.

Kommentarer på flere linjer

Python understøtter ikke native kommentarer på flere linjer, hvilket betyder, at der ikke er nogen særlig bestemmelse til at definere dem. På trods af dette bruges kommentarer, der strækker sig over flere linjer, ofte.

Du kan oprette en flerlinjekommentar ud fra flere enkeltlinjekommentarer ved at indlede hver linje med #:

# interpreter 
# ignores
# these lines

Du kan også bruge syntaksen for flerlinjestrenge. I Python kan du definere flerlinjestrenge ved at omslutte dem med """, tredobbelte dobbelte anførselstegn eller ''', tredobbelte enkeltstående anførselstegn:

print("Multi-Line Comment")
"""
This
String is 
Multi line 
"""

I koden ovenfor er strengen med flere linjer ikke tildelt en variabel, hvilket får strengen til at fungere som en kommentar. Ved kørselstid ignorerer Python strengen, og den bliver ikke inkluderet i bytekoden. Udførelse af ovenstående kode giver følgende output:

Multi-Line Comment

Særlige kommentarer

Ud over at gøre din kode læsbar tjener kommentarer også nogle særlige formål i Python, f.eks. planlægning af fremtidige kodetilføjelser og generering af dokumentation.

Python Docstring-kommentarer

I Python er docstrings kommentarer på flere linjer, der forklarer, hvordan en given funktion eller klasse skal bruges. Dokumentationen af din kode forbedres ved at oprette docstrings af høj kvalitet. Når du arbejder med en funktion eller klasse og bruger den indbyggede funktion help(obj), kan docstrings være nyttige til at give et overblik over objektet.

Python PEP 257 indeholder en standardmetode til at deklarere docstrings i Python, som vist nedenfor:

from collections import namedtuple
Person = namedtuple('Person', ['name', 'age'])

 def get_person(name, age, d=False):
    """
Returns a namedtuple("name", "age") object.
Also returns dict('name', 'age') if arg `d` is True

Arguments:
name  – first name, must be string
age   – age of person, must be int
d     – to return Person as `dict` (default=False)

"""
p = Person(name, age)
if d:
    return p._asdict()
return p

I koden ovenfor gav docstring detaljer om, hvordan den tilknyttede funktion fungerer. Med dokumentationsgeneratorer som Sphinx kan denne docstring bruges til at give brugerne af dit projekt et overblik over, hvordan denne metode skal bruges.

En docstring defineret lige under funktions- eller klassesignaturen kan også returneres ved hjælp af den indbyggede funktion help(). Funktionen help() tager et objekt- eller funktionsnavn som et argument og returnerer funktionens docstrings som output. I eksemplet ovenfor kan help(get_person) kaldes for at få vist docstrings, der er knyttet til funktionen get_person. Hvis du kører ovenstående kode i en interaktiv shell med -i -flaget, kan du se, hvordan denne docstring vil blive analyseret af Python. Kør ovenstående kode ved at skrive python -i file.py.

Skærmbillede: Python docstring-kommentarer parset i terminalen.
Pythons docstring-kommentarer analyseres i kommandolinjens grænseflade.

Funktionskaldet help(get_person) returnerer en docstring for din funktion. Udgangen indeholder get_person(name, age, d=False), som er en funktionssignatur, som Python automatisk tilføjer.

Attributten get_person.__ doc__ kan også bruges til at hente og ændre docstrings programmatisk. Efter tilføjelsen af “Some more new information” i eksemplet ovenfor vises det i det andet kald til help(get_person). Det er dog usandsynligt, at du vil få brug for at ændre docstrings dynamisk på kørselstid på denne måde.

TODO-kommentarer

Når du skriver kode, er der lejligheder, hvor du ønsker at fremhæve visse linjer eller hele blokke der kræver forbedring. Disse opgaver markeres med TODO-kommentarer. TODO-kommentarer er praktiske, når du planlægger opdateringer eller ændringer af din kode, eller hvis du ønsker at informere projektets brugere eller samarbejdspartnere om, at der stadig mangler at blive skrevet bestemte dele af koden i filen.

TODO-kommentarer skal ikke skrives som pseudokode – de skal blot kort forklare funktionen af den endnu ikke skrevne kode.

TODO-kommentarer og blokkommentarer på én linje ligner hinanden meget, og den eneste forskel mellem dem er, at TODO-kommentarer skal begynde med et TODO-præfiks:

# TODO Get serialized data from the CSV file
# TODO Perform calculations on the data
# TODO Return to the user

Det er vigtigt at bemærke, at selv om mange IDE’er kan fremhæve disse kommentarer for programmøren, ser Python-fortolkeren ikke TODO-kommentarer anderledes på TODO-kommentarer end blokkommentarer.

Bedste praksis ved skrivning af Python-kommentarer

Der er en række bedste praksis, der bør følges, når man skriver kommentarer for at sikre pålidelighed og kvalitet. Nedenfor er nogle tips til at skrive kommentarer af høj kvalitet i Python.

Undgå det indlysende

Kommentarer, der fastslår det indlysende, tilføjer ikke nogen værdi til din kode og bør undgås. For eksempel:

x = x + 4 # increase x by 4

Denne kommentar er ikke nyttig, da den blot angiver, hvad koden gør, uden at forklare, hvorfor det skal gøres. Kommentarer bør forklare “hvorfor” snarere end “hvad” i den kode, de beskriver.

Omskrevet på en mere brugbar måde kunne eksemplet ovenfor se således ud:

x = x + 4 # increase the border width

Hold Python-kommentarer korte og simple

Hold dine kommentarer korte og let forståelige. De bør være skrevet i standardprosa, ikke pseudokode, og bør erstatte behovet for at læse den egentlige kode for at få et generelt overblik over, hvad den gør. For mange detaljer eller komplekse kommentarer gør ikke programmørens arbejde lettere. For eksempel:

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

Kommentaren ovenfor giver mere information end nødvendigt for læseren. I stedet for at specificere kernen i logikken bør kommentarer give et generelt resumé af koden. Denne kommentar kan omskrives som:

# return area of cylinder
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

Brug identifikatorer med omhu

Identifikatorer bør anvendes med omhu i kommentarer. Hvis man ændrer identifikatornavne eller -betegnelser, kan det forvirre læseren. Eksempel:

# return class() after modifying argument
def func(cls, arg):
    return cls(arg+5)

Ovenstående kommentar nævner class og argument, som ikke findes i koden. Denne kommentar kan omskrives som:

# return cls() after modifying arg
def func(cls, arg):
    return cls(arg+5)

DRY og WET

Når du skriver kode, vil du gerne overholde DRY-princippet (don’t repeat yourself) og undgå WET-princippet (write everything twice).

Dette gælder også for kommentarer. Undgå at bruge flere udsagn til at beskrive din kode, og prøv at samle kommentarer, der forklarer den samme kode, i en enkelt kommentar. Det er dog vigtigt at være forsigtig, når du slår kommentarer sammen: En skødesløs sammenlægning af flere kommentarer kan resultere i en stor kommentar, der overtræder stilvejledninger og er svær for læseren at følge med i.

Husk, at kommentarer skal reducere læsetiden for koden.

"># function to do x work
def do_something(y):
    # x work cannot be done if y is greater than max_limit
    if y < 400:
      print('doing x work')

I koden ovenfor er kommentarerne unødigt fragmenterede og kan slås sammen til en enkelt kommentar:

"># function to do x if arg:y is less than max_limit
def  do_something(y):
    if y in range(400):
        print('doing x work')

Konsistent indrykning

Sørg for, at kommentarer er indrykket på samme niveau som den kode, de beskriver. Når de ikke er det, kan de være svære at følge.

Denne kommentar er f.eks. ikke indrykket eller placeret korrekt:

for i in range(2,20, 2):
# only even numbers
    if verify(i):
# i should be verified by verify()
        perform(x)

Den kan omskrives som følger:

# only even numbers
for i in range(2,20, 2):
    # i should be verified by verify()
    if verify(i):
        perform(x)

Opsummering

Kommentarer er en vigtig del af at skrive forståelig kode. Den investering du foretager i at skrive en kommentar er en investering, som dit fremtidige jeg – eller andre udviklere, der skal arbejde på din kodebase – vil sætte pris på. Ved at kommentere kan du også få en dybere indsigt i din kode.

I denne vejledning har du lært mere om kommentarer i Python, herunder de forskellige typer Python-kommentarer, hvornår du skal bruge dem hver især, og de bedste fremgangsmåder, du skal følge, når du opretter dem.

At skrive gode kommentarer er en færdighed, der skal studeres og udvikles. For at øve dig i at skrive kommentarer kan du overveje at gå tilbage og tilføje kommentarer til nogle af dine tidligere projekter. Hvis du vil have inspiration og se bedste praksis i praksis, kan du se godt dokumenterede Python-projekter på GitHub.

Når du er klar til at gøre dine egne Python-projekter live, kan Kinstas Applikation Hosting-platform få din kode fra GitHub til skyen på få sekunder.

Vivek Singh

Vivek er en Python- og Django-udvikler, som altid er klar til at lære og lære nye ting til andre udviklere.