Zo kun je programmeren in Python - deel 8

Hier vind je les 1 van de Python-cursus.

Verkeerde gewoontes leer je niet snel af, daarom dat we nu even een stapje terugdoen en nadenken over wat ‘goede code’ is. Na deze les kun je code produceren die niet alleen goed gedocumenteerd en goed getest is, maar weet je ook hoe je informatie over Python-modules opzoekt met de helpfunctie.

Code documenteren met commentaar

Tot nu toe schreven we onze code zonder enige vorm van documentatie. Als je met anderen samenwerkt aan een programma, is het belangrijk dat je die documenteert, zodat je anderen duidelijk maakt wat je met je code bedoelt. Maar ook als je helemaal alleen programmeert, is documentatie geen overbodige luxe. Zo begrijp je je eigen code nog als je er over een jaar opnieuw naar kijkt.

De eerste manier om je code te documenteren is met commentaar. Alles na het #-teken (hekje) tot het einde van de regel (behalve als het hekje ín een string voorkomt) is commentaar en wordt door Python genegeerd. Op die manier kun je een uitleg voor jezelf of anderen schrijven. Als je bijvoorbeeld in de functie is_palindroom van deel 6 in de war raakt met die indexen, schrijf er dan gerust wat commentaar bij:

if letters[0] != letters[-1]: # Als de eerste en de laatste letter verschillen

Het getuigt van goede stijl om twee spaties tussen je code en het erna volgende commentaarteken te houden en één spatie tussen het commentaarteken en je commentaar. Overigens kun je ook commentaar op een nieuwe losstaande regel beginnen, dan spreken we van een commentaarregel:

# Als de eerste en de laatste letter verschillen

if letters[0] != letters[-1]:

Het is de gewoonte om een commentaarregel te zetten op de regel vóór de regel waarover hij gaat.

Code uitcommentariëren

Code documenteren met docstrings

Commentaar gebruik je om te documenteren waarom je iets doet en hoe je het doet, maar voor gebruikers van je code is vooral belangrijk wat die doet. Om dat te documenteren, gebruik je docstrings: in het begin van elke module, elke klasse en elke functie of methode geef je met een string tussen drie dubbele aanhalingstekens aan wat het stuk code doet.

Zo zouden we onze klassen uit de vorige les als volgt kunnen documenteren:

"""Klassen om met tweedimensionale, driedimensionale en hogerdimensionale punten te werken."""

import math

class Point:
"""Stelt een punt voor in een willekeurig aantal dimensies."""

def __init__(self, *coordinates):
"""Initialiseer het punt met de opgegeven coördinaten."""
self.coordinates = list(coordinates)

def __repr__(self):
"""Geef een leesbare voorstelling van het punt terug."""
return 'Point(' + ', '.join(str(co) for co in self.coordinates) + ')'

def displacement(self, other_point):
"""Geef het verschil terug tussen dit punt en een ander punt.

De overeenkomstige coördinaten worden van elkaar afgetrokken.

Voorbeeld: het verschil tussen Point(1, 4, 2) en Point(3, 4, 1) is gelijk aan Point(2, 0, -1).
"""
return Point(*[a-b for a, b in zip(other_point.coordinates, self.coordinates)])

def distance(self, other_point):
"""Geef de Euclidische afstand terug tussen dit punt en een ander punt."""
relative_position = self.displacement(other_point)
return math.sqrt(sum(i**2 for i in relative_position.coordinates))
class Point2D(Point):
"""Stelt een tweedimensionaal punt voor."""

def __init__(self, x=0, y=0):
"""Initialiseer het punt met de opgegeven x- en y-coördinaten."""
Point.__init__(self, x, y)
self.x = x
self.y = y
def get_x(self):

"""De x-coördinaat van het punt."""
return self.coordinates[0]

def set_x(self, x):
self.coordinates[0] = x

x = property(get_x, set_x)

def get_y(self):
"""De y-coördinaat van het punt."""
return self.coordinates[1]

def set_y(self, y):
self.coordinates[1] = y

y = property(get_y, set_y)

Je ziet hier dat documentatie niet lang hoeft te zijn. De docstrings bij de module, de klassen en bij de meeste methodes zijn maar één regel lang.

De moeilijkste methode om te begrijpen is displacement en daarom is het zinvol om daar wat meer uitleg bij te geven. Bij een docstring van meer dan één regel raden we aan om na de eerste regel een lege regel te houden, en om de drie dubbele aanhalingstekens op het einde op een nieuwe regel te zetten. Dat geeft wat meer overzicht.

Merk op: bij onze eigenschappen x en y van de klasse Point2D documenteren we alleen de methode die de waarde van de eigenschap opvraagt. Zo toont de ingebouwde helpfunctie van Python (die we op het einde van deze les bespreken) deze documentatie bij de eigenschap.

Interactieve voorbeelden in docstrings

We hebben in de docstring van de methode displacement al een voorbeeld van het gebruik van de methode gegeven als documentatie. Maar dat bleef nogal informeel. We kunnen die documentatie ook in de vorm van echte Python-code doen die je in een interactieve terminalsessie zou kunnen invoeren. Zo kan de gebruiker die de documentatie leest, onmiddellijk de voorbeelden kopiëren uit de documentatie en plakken in de Python-interpreter om ze uit te proberen. Dat zou voor de methode displacement er dan als volgt uitzien:

def displacement(self, other_point):
"""Geef het verschil terug tussen dit punt en een ander punt.

De overeenkomstige coördinaten worden van elkaar afgetrokken.

>>> Point(1, 4, 2).displacement(Point(3, 4, 1))
Point(2, 0, -1)
"""
return Point(*[a-b for a, b in zip(other_point.coordinates, self.coordinates)])

Je ziet hier dat je de code na de >>> exact in een Python-terminalsessie zou kunnen invoeren en dan ook het resultaat zou krijgen dat hier staat. In feite hebben we wat hier staat gewoon eerst in de terminal van Thonny ingevoerd en dan samen met de uitvoer gekopieerd en hier in de docstring geplakt.

Code testen met doctest

Stel dat je nu ooit de code van de methode displacement aanpast omdat je denkt een verbetering te zien, maar er een fout in maakt, waardoor het resultaat verkeerd is. Dan kun je dat testen door de voorbeeldcode in je docstring uit te voeren in een Python-terminalsessie. Voer je de code uit en komt het resultaat niet overeen met de uitvoer in de docstring, dan klopt je code niet meer.

Maar zouden we die test niet automatisch kunnen doen? Jazeker! Python kent daarvoor de module doctest, die automatisch alle docstrings in een module kan testen op interactieve voorbeelden. Dat voer je als volgt uit in een Linux- of macOS-terminal of de Windows Opdrachtprompt:

python3 -m doctest -v point.py

Hierbij is point.py de naam van de module met je code erin. Je krijgt dan als uitvoer de tests die doctest in je docstrings ziet en het resultaat. Als je het alleen wilt zien als een test een fout vindt, haal dan de optie -v weg. Stel dat je bijvoorbeeld per ongeluk de * vergeten bent in de methode displacement om de lijst naar een willekeurig aantal argumenten voor de klasse Point om te zetten, dan zal doctest die fout opmerken met de volgende melding:

**********************************************************************

File "point.py", line 21, in point.Point.displacement

Failed example:

Point(1, 4, 2).displacement(Point(3, 4, 1))

Expected:

Point(2, 0, -1)

Got:

Point([2, 0, -1])

**********************************************************************

1 items had failures:

1 of

***Test Failed*** 1 failures.

Een goede manier van programmeren is dan ook dat je je code zoveel mogelijk documenteert met docstrings en daarin ook interactieve voorbeelden opneemt, die je na elke wijziging van je code automatisch test met doctest om je ervan te verzekeren dat je geen fouten hebt geïntroduceerd.

De helpfunctie gebruiken

Als je code is gedocumenteerd, hoef je niet je codebestand in Thonny te openen om de documentatie te bekijken. Je kunt dit in een interactieve Python-sessie, bijvoorbeeld in Thonny, maar ook in een Python-sessie in een Linux- of macOS-terminal of de Windows Opdrachtprompt. Het enige wat je hoeft te doen, is de functie help op te roepen met de naam van de module, klasse, functie of methode waarvoor je de documentatie wilt zien. Bijvoorbeeld in Thonny:

>>> help(Point.displacement)

Help on function displacement in module __main__:

displacement(self, other_point)

Geef het verschil terug tussen dit punt en een ander punt.

De overeenkomstige coördinaten worden van elkaar afgetrokken.

>>> Point(1, 4, 2).displacement(Point(3, 4, 1))

Point(2, 0, -1)

Overigens zijn alle standaardmodules van Python uitgebreid gedocumenteerd met docstrings. Daardoor kun je van alle modules, klassen, functies en methodes heel eenvoudig documentatie opvragen in je Python-terminalsessie. Let er wel op dat je een module eerst dient te importeren voordat je er documentatie van kunt opvragen met help.

Samenvatting

In deze les ging het minder over het programmeren zelf, maar over het documenteren en testen van je Python-programma’s en het uitzoeken van meer informatie over de standaard Python-modules of je eigen modules. Hoe complexer je programma’s zijn, hoe belangrijker dit soort zaken rond je code zijn. Maak er daarom een gewoonte van om documentatie en tests niet als een nabeschouwing te zien, maar al tijdens de ontwikkeling van je programma in je code te integreren. In de volgende les maken we het nog complexer: dan gaan we extra modules installeren die niet in Python ingebouwd zijn.

Opdracht 1

Uitwerking opdracht 1

Opdracht 2

Uitwerking opdracht 2

Cheatsheet