Kommentarer är anteckningar som programmerare lägger till i sin kod för att förklara vad koden ska göra. De kompilatorer eller tolkar som omvandlar kod till handling ignorerar kommentarer, men de kan vara viktiga för att hantera applikations-projekt.

Kommentarer hjälper till att förklara din Pythonkod för andra programmerare och kan påminna dig om varför du gjorde som du gjorde. De gör det lättare att felsöka och revidera kod genom att hjälpa framtida programmerare att förstå designvalen bakom applikationen.

Även om kommentarer i första hand är till för utvecklare så kan den även vara till hjälp för användarna av din kod. Effektiva kommentarer kan exempelvis skapa en utmärkt dokumentation. Med hjälp av dokument-generatorer som Sphinx för Pythonprojekt så kan kommentarer i din kod ge innehåll till din dokumentation.

Låt oss titta under huven på kommentarer i Python.

Kommentarer i Python

Enligt Python PEP 8 Style Guide så finns det flera saker som man bör tänka på när man skriver kommentarer:

  • Kommentarer ska alltid vara fullständiga och koncisa meningar.
  • Det är bättre att inte ha någon kommentar alls än en kommentar som är svårförståelig eller felaktig.
  • Kommentarer bör uppdateras regelbundet för att återspegla ändringar i koden.
  • För många kommentarer kan vara störande och försämra kodens kvalitet. Kommentarer behövs inte när kodens syfte är uppenbart.

I Python så deklareras en rad som en kommentar när den börjar med symbolen #. När Python-tolken stöter på # i din kod så ignorerar den allt som följer efter den symbolen och ger inte upphov till något fel. Det finns två sätt att deklarera kommentarer på en enda rad: inline-kommentarer och blockkommentarer.

Inline-kommentarer

Inline-kommentarer ger korta beskrivningar av variabler och enkla operationer och skrivs på samma rad som kodförklaringen:

border = x + 10  # Make offset of 10px

Kommentaren förklarar kodens funktion i samma uttalande som koden.

Blockkommentarer

Blockkommentarer används för att beskriva en komplex logik i koden. Blockkommentarer i Python är uppbyggda på samma sätt som inline-kommentarer – den enda skillnaden är att blockkommentarer skrivs på en separat rad:

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)

Observera att när blockkommentarer används så skrivs kommentarerna ovanför den kod som de förklarar. Pythons PEP8 Style Guide föreskriver att en kodrad inte får innehålla mer än sjuttionio tecken, och inline-kommentarer driver ofta upp raderna över denna längd. Av den anledningen så skrivs blockkommentarer för att beskriva koden på separata rader.

Kommentarer på flera rader

Python har inte naturligt stöd för kommentarer med flera rader, vilket innebär att det inte finns någon särskild bestämmelse för att definiera dem. Trots detta så används ofta kommentarer som sträcker sig över flera rader.

Du kan skapa en flerradskommentar av flera enradskommentarer genom att inleda varje rad med #:

# interpreter 
# ignores
# these lines

Du kan även använda syntaxen för strängar med flera rader. I Python så kan du definiera strängar med flera rader genom att omsluta dem med """, tredubbla dubbla citationstecken eller ''', tredubbla enkla citationstecken:

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

I koden ovan så tilldelas strängen med flera rader inte en variabel, vilket gör att strängen fungerar som en kommentar. Vid körning så ignorerar Python strängen och den inkluderas inte i bytekoden. Exekvering av ovanstående kod ger följande utdata:

Multi-Line Comment

Särskilda kommentarer

Förutom att göra din kod läsbar så har kommentarer även vissa speciella syften i Python, t.ex. att planera framtida kodtillägg och skapa dokumentation.

Kommentarer till Python Docstring

Docstrings i python är kommentarer på flera rader som förklarar hur man använder en viss funktion eller klass. Dokumentationen av din kod förbättras genom skapandet av högkvalitativa docstrings. När du arbetar med en funktion eller klass och använder den inbyggda funktionen help(obj) så kan docstrings vara till hjälp för att ge en översikt över objektet.

Python PEP 257 tillhandahåller en standardmetod för att deklarera docstrings i Python, som visas nedan:

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 ovan så ger docstring detaljer om hur den tillhörande funktionen fungerar. Med dokumentations-generatorer som Sphinx så kan denna docstring användas för att ge användarna av ditt projekt en översikt över hur man använder denna metod.

En dokumentationssträng som definieras precis under funktions- eller klassignaturen kan också returneras med hjälp av den inbyggda funktionen help(). Funktionen help() tar ett objekt- eller funktionsnamn som argument och returnerar funktionens dokumentsträngar som utmatning. I exemplet ovan så kan help(get_person) anropas för att visa de dokumentsträngar som är kopplade till funktionen get_person. Om du kör koden ovan i ett interaktivt skal med flaggan -i så kan du se hur den här dokumentsträngen analyseras av Python. Kör ovanstående kod genom att skriva python -i file.py.

Pythons dokumentsträngskommentarer analyseras i kommandoradsgränssnittet.
Pythons dokumentsträngskommentarer analyseras i kommandoradsgränssnittet.

Funktionsanropet help(get_person) returnerar en docstring för din funktion. Utdatan innehåller get_person(name, age, d=False), som är en funktionssignatur som Python lägger till automatiskt.

Attributet get_person.__ doc__ kan också användas för att hämta och ändra docstrings programmatiskt. Efter att ha lagt till ”Some more new information” i exemplet ovan så visas detta i det andra anropet till help(get_person). Det är dock osannolikt att du behöver ändra docstrings dynamiskt vid körning på det här sättet.

TODO-kommentarer

När du skriver kod så finns det tillfällen då du vill markera vissa rader eller hela block för förbättring. Dessa uppgifter markeras med TODO-kommentarer. TODO-kommentarer är praktiska när du planerar uppdateringar eller ändringar av din kod. Det kan även hända att du vill informera projektets användare eller samarbetspartners om att specifika avsnitt av filens kod återstår att skriva.

TODO-kommentarer ska inte skrivas som pseudokod – de behöver bara ge en kortfattad förklaring av funktionen hos den ännu inte skrivna koden.

TODO-kommentarer och enradiga blockkommentarer är mycket lika varandra, och den enda skillnaden mellan dem är att TODO-kommentarer måste börja med ett TODO-prefix:

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

Det är viktigt att notera att även om många IDE: er kan markera dessa kommentarer för programmeraren, så gör Python-tolken inte skillnad mellan TODO-kommentarer och blockkommentarer.

Bästa praxis när du skriver Pythonkommentarer

Det finns ett antal rekommenderade metoder som bör följas när man skriver kommentarer, för att säkerställa tillförlitlighet och kvalitet. Nedan så följer några tips för att skriva högkvalitativa kommentarer i Python.

Undvik det uppenbara

Kommentarer som anger det uppenbara tillför inget värde till din kod och bör undvikas. Exempelvis:

x = x + 4 # increase x by 4

Den kommentaren är inte användbar, eftersom den bara anger vad koden gör utan att förklara varför den måste göras. Kommentarer bör förklara ”varför” snarare än ”vad” i den kod som de beskriver.

Omskrivet på ett mer användbart sätt skulle exemplet ovan kunna se ut så här:

x = x + 4 # increase the border width

Håll Pythonkommentarerna korta och snygga

Håll dina kommentarer korta och lättförståeliga. De bör vara skrivna i standardprosa, inte i pseudokod, och bör ersätta behovet av att läsa själva koden för att få en allmän överblick över vad den gör. Alltför detaljerade eller komplexa kommentarer gör inte programmerarens arbete lättare. Exempelvis:

# 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 ovan ger mer information än vad som är nödvändigt för läsaren. Istället för att specificera kärnlogiken så bör kommentarerna ge en allmän sammanfattning av koden. Denna kommentar kan skrivas om till följande:

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

Använd identifierare med försiktighet

Identifierare bör användas med försiktighet i kommentarer. Om man ändrar namn eller fall på identifierare så kan detta förvirra läsaren. Exempelvis:

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

Ovanstående kommentar nämner class och argument, som inte finns i koden. Kommentaren kan skrivas om till följande:

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

DRY och WET

När du skriver kod så bör du följa DRY-principen (upprepa inte dig själv) och undvika WET-principen (skriva allting två gånger).

Detta gäller även för kommentarer. Undvik att använda flera uttalanden för att beskriva din kod och försök att slå ihop kommentarer som förklarar samma kod till en enda kommentar. Det är dock viktigt att vara försiktig när du slår ihop kommentarer: en slarvig sammanslagning av flera kommentarer kan resultera i en enorm kommentar som bryter mot stilguider och som är svår för läsaren att följa.

Kom ihåg att kommentarer ska minska lästiden för 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 ovan så är kommentarerna onödigt splittrade och kan slås samman till en enda 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')

Konsekvent indragning

Se till att kommentarerna är indragna på samma nivå som den kod de beskriver. De kan annars vara svåra att följa.

Den här kommentaren är exempelvis inte indragen eller placerad på rätt sätt:

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

Den kan skrivas om på följande sätt:

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

Sammanfattning

Kommentarer är en viktig del i skrivandet av en begriplig kod. Den investering som du gör när du skriver en kommentar är en investering som ditt framtida jag – eller andra utvecklare som behöver arbeta med din kodbas – kommer att uppskatta. Genom att kommentera så kan du även få djupare insikter i din kod.

I den här guiden så har du lärt dig mer om kommentarer i Python, inklusive de olika typerna av Pythonkommentarer. Du har lärt dig när du ska använda var och en av dem och de rekommenderade metoderna när du skapar dem.

Att skriva bra kommentarer är en färdighet som måste studeras och utvecklas. För att öva sig på att skriva kommentarer så kan du överväga att gå tillbaka och lägga till kommentarer i några av dina tidigare projekt. För inspiration och för att se bästa praxis så kan du kolla in väldokumenterade Pythonprojekt på GitHub.

När du är redo att omvandla dina egna Python-projekt till live så kan Kinsta’s plattform för applikationshosting få din kod från GitHub till molnet på några sekunder.

Vivek Singh

Vivek is a Python and Django developer who's always ready to learn and teach new things to fellow developers.