Comments zijn notities die programmeurs aan hun code toevoegen om uit te leggen wat die code moet doen. De compilers of interpretators die code omzetten in actie negeren comments, maar ze kunnen essentieel zijn voor het beheer van softwareprojecten.

Comments helpen om je Python code uit te leggen aan andere programmeurs en kan je eraan herinneren waarom je de keuzes hebt gemaakt die je hebt gemaakt. Comments maken het debuggen en herzien van code gemakkelijker door toekomstige programmeurs te helpen de ontwerpkeuzes achter software te begrijpen.

Hoewel comments vooral bedoeld zijn voor developers, kan het schrijven van effectieve comments ook helpen bij het maken van uitstekende documentatie voor de gebruikers van je code. Met behulp van documentgenerators zoals Sphinx voor Python projecten, kunnen comments in je code content geven voor je documentatie.

Laten we eens kijken onder de motorkap van comments in Python.

Comments in Python

Volgens de Python PEP 8 Style Guide zijn er verschillende dingen waar je op moet letten bij het schrijven van comments:

  • Comments moeten altijd volledige en beknopte zinnen zijn.
  • Het is beter om helemaal geen comments te hebben dan comments die moeilijk te begrijpen of onnauwkeurig zijn.
  • Comments moeten regelmatig worden bijgewerkt om veranderingen in je code weer te geven.
  • Te veel comments kan afleiden en de kwaliteit van de code verminderen. Comments zijn niet nodig als het doel van de code duidelijk is.

In Python wordt een regel aangegeven als comment als hij begint met het symbool #. Wanneer de Python interpreter # tegenkomt in je code, negeert hij alles wat na dat symbool komt en produceert hij geen fout. Er zijn twee manieren om comments van één regel te declaren: inlinecomments en blokcomments.

Inlinecomments

Inline comments geven korte beschrijvingen van variabelen en eenvoudige bewerkingen en wordt op dezelfde regel geschreven als het code-statement:

border = x + 10  # Make offset of 10px

De comment legt de functie van de code uit in hetzelfde statement als de code.

Blokcomments

Blokcomments worden gebruikt om complexe logica in de code te beschrijven. Blokcomments in Python zijn vergelijkbaar met inlinecomments – het enige verschil is dat blokcomments op een aparte regel worden geschreven:

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)

Let op dat bij gebruik van blokcomments de comments worden geschreven boven de code die het uitlegt. De Python PEP8 Style Guide schrijft voor dat een regel code niet meer dan negenenzeventig tekens mag bevatten, en inlinecomments gaan vaak over deze lengte heen. Daarom worden blokcomments geschreven om de code op aparte regels te beschrijven.

Comments van meerdere regels

Python ondersteunt van zichzelf geen comments van meerdere regels, wat betekent dat er geen speciale voorziening is om ze te definiëren. Desondanks worden vaak comments gebruikt die meerdere regels beslaan.

Je kunt een meerregelig comment maken van meerdere eenregelige comments door elke regel vooraf te laten gaan door #:

# interpreter 
# ignores
# these lines

Je kunt ook de syntaxis van meerregelige strings gebruiken. In Python kun je meerregelige strings definiëren door ze in te sluiten tussen """, drie dubbele aanhalingstekens, of ''', drie enkele aanhalingstekens:

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

In bovenstaande code wordt de meerregelige string niet toegewezen aan een variabele, waardoor de string werkt als een comments. Tijdens runtime negeert Python de string, en hij wordt niet opgenomen in de bytecode. Uitvoering van bovenstaande code levert de volgende uitvoer op:

Multi-Line Comment

Speciale comments

Naast het leesbaar maken van je code, dienen comments ook enkele speciale doelen in Python, zoals het plannen van toekomstige toevoegingen aan de code en het genereren van documentatie.

Python Docstring comments

In Python zijn docstrings meerregelig comments die uitleggen hoe een bepaalde functie of klasse gebruikt moet worden. De documentatie van je code wordt verbeterd door het maken van hoogwaardige docstrings. Tijdens het werken met een functie of klasse en het gebruik van de ingebouwde functie help(obj), kunnen docstrings behulpzaam zijn bij het geven van een overzicht van het object.

Python PEP 257 biedt een standaardmethode voor het declareren van docstrings in Python, zoals hieronder weergegeven:

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

In de code hierboven geeft de docstring details over hoe de bijbehorende functie werkt. Met documentatiegenerators als Sphinx kan deze docstring gebruikt worden om gebruikers van je project een overzicht te geven van het gebruik van deze methode.

Een docstring die net onder de functie of klassensignature is gedefinieerd, kan ook worden teruggegeven door de ingebouwde functie help() te gebruiken. De functie help() neemt een object of functienaam als argument, en geeft de docstrings van de functie terug als uitvoer. In het bovenstaande voorbeeld kan help(get_person) worden aangeroepen om de docstrings van de functie get_person te tonen. Als je bovenstaande code uitvoert in een interactieve shell met de vlag -i, kun je zien hoe deze docstring door Python wordt geparseerd. Voer de bovenstaande code uit door te typen python -i file.py.

Screenshot: Python docstring comments geparseerd in de terminal.
Python docstring commentaar geparseerd in de commandoregel interface.

De functiecall help(get_person) geeft een docstring voor je functie terug. De output bevat get_person(name, age, d=False), wat een functiesignatuur is die Python automatisch toevoegt.

Het get_person.__ doc__ attribuut kan ook gebruikt worden om docstrings programmatisch op te vragen en te wijzigen. Na het toevoegen van “Some more new information” in het bovenstaande voorbeeld, verschijnt het in de tweede aanroep van help(get_person). Toch is het onwaarschijnlijk dat je op deze manier dynamisch docstrings tijdens runtime moet wijzigen.

TODO comments

Bij het schrijven van code zijn er momenten waarop je bepaalde regels of hele blokken wilt verbeteren. Deze taken worden gemarkeerd door TODO comments. TODO comments komen van pas als je updates of wijzigingen van je code plant, of als je de gebruikers of medewerkers van het project wilt laten weten dat specifieke delen van de code van het bestand nog geschreven moeten worden.

TODO comments moeten niet geschreven worden als pseudocode – ze hoeven alleen maar kort de functie van de nog niet geschreven code uit te leggen.

TODO comments en eenregelige blokcomments lijken erg op elkaar, en het enige onderscheid tussen beide is dat TODO comments moeten beginnen met een TODO prefix:

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

Het is belangrijk op te merken dat, hoewel veel IDE’s deze comments kunnen markeren voor de programmeur, de Python interpreter TODO comments niet anders bekijkt dan blokcomments.

Best practices bij het schrijven van Python comments

Er zijn een aantal best practices die gevolgd moeten worden bij het schrijven van comments om betrouwbaarheid en kwaliteit te garanderen. Hieronder volgen enkele tips voor het schrijven van kwalitatief goede comments in Python.

Vermijd het voor de hand liggende

Comments die overduidelijk zijn, hebben geen toegevoegde waarde voor je code en moet worden vermeden. Bijvoorbeeld:

x = x + 4 # increase x by 4

Die comment is niet nuttig, omdat het eenvoudigweg zegt wat de code doet zonder uit te leggen waarom het gedaan moet worden. Comments moeten eerder het “waarom” uitleggen dan het “wat” van de code die het beschrijft.

Beter herschreven zou het bovenstaande voorbeeld er zo uit kunnen zien:

x = x + 4 # increase the border width

Houd Python comments kort en krachtig

Houd je comments kort en gemakkelijk te begrijpen. Ze moeten geschreven zijn in standaard proza, niet in pseudocode, en moeten de noodzaak vervangen om de eigenlijke code te lezen om een algemeen overzicht te krijgen van wat het doet. Te veel details of ingewikkeld comments maken het werk van een programmeur niet eenvoudiger. Bijvoorbeeld:

# 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)

De comment hierboven geeft meer informatie dan nodig is voor de lezer. In plaats van de logica te specificeren, zouden comments een algemene samenvatting van de code moeten geven. Deze comment kan herschreven worden als:

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

Gebruik identifiers zorgvuldig

Identifiers moeten zorgvuldig gebruikt worden in comments. Het veranderen van namen of gevallen van identifiers kan de lezer in verwarring brengen. Voorbeeld:

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

De bovenstaande comment noemt class en argument, die geen van beide in de code voorkomen. Deze comment kan worden herschreven als:

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

DRY en WET

Als je code schrijft, wil je je houden aan het DRY (don’t repeat yourself) principe en WET (write everything twice) vermijden.

Dit geldt ook voor comments. Vermijd het gebruik van meerdere declarations om je code te beschrijven, en probeer comments die dezelfde code uitleggen samen te voegen tot één comment. Het is echter belangrijk om voorzichtig te zijn met het samenvoegen van comments: onzorgvuldig samenvoegen van meerdere comments kan resulteren in één enorme comment die in strijd is met de stijlgidsen en moeilijk te volgen is voor de lezer.

Onthoud dat comments de leestijd van de code moeten verkorten.

"># 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')

In bovenstaande code is de comment onnodig gefragmenteerd, en kan het worden samengevoegd tot één comment:

"># 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')

Consistent inspringen

Zorg ervoor dat comments op hetzelfde niveau inspringen als de code die het beschrijft. Als dat niet het geval is, kunnen ze moeilijk te volgen zijn.

Deze comment is bijvoorbeeld niet goed ingesprongen of gepositioneerd:

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

Het kan als volgt herschreven worden:

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

Samenvatting

Comments zijn een belangrijk onderdeel van het schrijven van begrijpelijke code. De investering die je doet in het schrijven van comments is er een die je toekomstige zelf – of andere developers die aan je codebase moeten werken – zullen waarderen. Met comments kun je ook dieper inzicht krijgen in je code.

In deze tutorial heb je meer geleerd over comments in Python, inclusief de verschillende soorten Python comments, wanneer je elk van hen moet gebruiken, en de best practices om te volgen bij het maken ervan.

Het schrijven van goede comments is een vaardigheid die bestudeerd en ontwikkeld moet worden. Om het schrijven van comments te oefenen, kun je overwegen terug te gaan en comments toe te voegen aan enkele van je eerdere projecten. Kijk voor inspiratie en om de best practices in actie te zien naar goed gedocumenteerde Python projecten op GitHub.

Als je klaar bent om je eigen Python projecten live te zetten, kan Kinsta’s Applicatie Hosting platform je code in enkele seconden van GitHub naar de cloud brengen.

Vivek Singh

Vivek is een Python en Django developer die altijd bereid is om andere developers nieuwe dingen te leren.