Een functie documenteren

De vorige les introduceerde de REPL als een plek om Python instructie voor instructie te verkennen. We blijven die hier gebruiken, deze keer om informatie binnen functies te bekijken.

De functies in dit hoofdstuk worden flexibeler. Ze hebben standaardwaarden, benoemde instellingen en optionele waarden. Naarmate die flexibiliteit groeit, moet iemand die een functie gebruikt de regels kunnen kennen zonder elke regel van het blok te lezen.

Een percentagefunctie heeft bijvoorbeeld een positieve total nodig. Ze geeft een getal terug en werpt een fout op wanneer die regel wordt overtreden. We kunnen die feiten vastleggen als de belofte van de functie:

• welke waarden ze verwacht;

• wat ze teruggeeft;

• belangrijke regels of fouten.

De implementatie laat zien hoe de functie werkt. Python biedt een manier om een korte uitleg bij de functie zelf te bewaren. Voordat we die gebruiken, heb je één nieuwe manier nodig om een string te schrijven.

Driedubbele aanhalingstekens voor strings

Tot nu toe schreef je strings tussen één paar aanhalingstekens, zoals "hello". Een string kan ook beginnen en eindigen met drie dubbele aanhalingstekens:

De waarde heeft nog steeds het type str. De driedubbele aanhalingstekens veranderen alleen hoe je die schrijft.

Een nuttig verschil is dat een string tussen driedubbele aanhalingstekens op een nieuwe regel kan doorgaan:

Python accepteert ook drie enkele aanhalingstekens. In deze cursus gebruiken we drie dubbele aanhalingstekens voor functiedocumentatie, omdat dat de gebruikelijke Python-stijl is.

Wanneer de eerste string documentatie wordt

Een string tussen driedubbele aanhalingstekens is niet automatisch documentatie. De positie binnen de functie geeft haar een speciale taak.

Wanneer een string de eerste instructie in een functie is, bewaart Python die als de docstring van de functie. Een docstring legt uit waarop andere code kan vertrouwen wanneer die de functie gebruikt.

Je leerde in Python-basis I dat raise een functie stopt en meldt waarom ze geen normaal resultaat kon teruggeven. De docstring en validatie kunnen bij elkaar staan:

def percentage(score, total):
    """Return score as a percentage of a positive total."""
    if total <= 0:
        raise ValueError("total must be positive")
    return score / total * 100

Hier is de string tussen driedubbele aanhalingstekens de eerste instructie en wordt die dus de docstring. Ze legt het resultaat en de regel voor een positief totaal in één zin uit.

De functie help() van Python kan die documentatie tonen:

help(percentage)

Beschrijf de belofte, niet elke stap

Deze docstring is zwak:

"""Divide score by total, multiply by 100, and return it."""

Die herhaalt de implementatie. Een sterkere docstring benoemt de belofte en de belangrijke beperking:

"""Return score as a percentage of a positive total."""

Verken docstrings in de REPL

Het paneel naast deze les is een Python-REPL. Probeer bij de prompt >>> deze opdrachten één voor één:

help(len)
help(print)
help("python land".strip)

Deze functies hebben al docstrings. Je hoeft niet elk detail te begrijpen dat help() toont. Zoek naar de functienaam, de waarden die de functie accepteert en de eerste zin die het resultaat beschrijft.

De docstring zelf is ook beschikbaar via het attribuut __doc__ van een functie. Vergelijk deze twee REPL-instructies:

len.__doc__
help(len)

len.__doc__ evalueert naar de opgeslagen string, dus de REPL toont die waarde. help(len) presenteert dezelfde documentatie in een uitgebreidere hulpweergave.

Geef nu je eigen functie een docstring. Voer deze regels in de REPL in en druk daarna nog één keer op Enter op de lege regel met ... om de functie af te ronden:

def double(number):
    """Return number multiplied by two."""
    return number * 2

Bekijk en gebruik de functie daarna:

double.__doc__
help(double)
double(6)

Probeer de docstring te veranderen en de functie opnieuw te definiëren. De volgende aanroep van help(double) toont je nieuwe beschrijving.