Antwoord.

Geschiedenis van de kwestie

In Python wordt al sinds de vroegste versies documentatie van de code aangemoedigd via docstrings. Met de komst van Python 3.5 (PEP 484) werden type-annotaties (type hints) toegevoegd om de leesbaarheid te verbeteren en de ondersteuning van type-analyse tools (zoals mypy, pyright, etc.) te verbeteren. Op deze manier kunnen documentatie en typing worden gecombineerd in de definitie van functies en klassen.

Probleem

Zonder type-annotaties is het moeilijk om snel te begrijpen waar de functie mee werkt en wat je ervan kunt verwachten. Het gebrek aan goede docstrings leidt tot misverstanden over de interface en gebruiksfouten. Als type hints of docstrings verkeerd worden gebruikt, verstoort dit de statische analyse en vermindert het de ondersteuning van de code.

Oplossing

Gebruik meerregelige docstrings om het doel van de functie, parameters en resultaat te documenteren, en type hints om expliciet de types van argumenten en geretourneerde waarden aan te geven.

Voorbeeldcode:

def add_numbers(a: int, b: int) -> int:
    """
    Voegt twee gehele getallen samen en retourneert het resultaat.

    :param a: Eerste operand, int
    :param b: Tweede operand, int
    :return: Som, int
    """
    return a + b

Belangrijke kenmerken:

Docstring wordt opgeslagen in doc en is beschikbaar voor IDE's, help(), en autogenerators voor documentatie
Type-annotaties zijn beschikbaar via annotations; ze beïnvloeden de uitvoering van de code niet, alleen voor analyse
Het gecombineerde gebruik vergemakkelijkt grootschalige ondersteuning en onboarding van nieuwe programmeurs.

Vragen met een haakje.

Kunnen type-annotaties invloed hebben op de uitvoering van het programma?

Nee. Type-annotaties (type hints) worden niet gecontroleerd door de Python-interpreter tijdens uitvoering en dienen uitsluitend voor analysetools en IDE's, alsook voor autogeneratie van documentatie. Ze leiden niet tot runtime-fouten en zijn altijd optioneel.

Kun je type-annotaties gebruiken om de waarden van een parameter te beperken?

Nee. Het specificeren van een type, bijvoorbeeld x: int, voorkomt niet dat een waarde van een ander type in de praktijk wordt doorgegeven. Hiervoor kun je runtime-controles (assert/isinstance) gebruiken, maar niet type hints — ze worden niet automatisch verifiziert.

Kun je opmerkingen # type: ... gebruiken in plaats van annotaties? Waar kan dit nuttig zijn?

Ja, dit is toegestaan als compatibiliteit met Python 2 of oudere codebases nodig is. Bijvoorbeeld:

def foo(x, y):     # type: (int, str) -> bool
    pass

Dit wordt begrepen door mypy en soortgelijke tools, net als de moderne syntaxis, maar in nieuwe projecten is het beter om de standaardannotaties te gebruiken.

Veelvoorkomende fouten en antipatterns

Ontbreken van een docstring of een lege docstring voor publieke functies en klassen
Onjuiste type-aanduidingen — bijvoorbeeld, List in plaats van list of spelfouten in types (vooral bij complexe verzamelingen)
Gebruik van type hints zonder documentatie bij te werken en vice versa

Voorbeeld uit de praktijk

Negatief geval

In een groot project zijn functies helemaal niet voorzien van docstrings en type hints — de ontwikkelaar besteedt veel tijd aan bestuderen en debuggen, en maakt vaak fouten met typen en de bedoeling van de invoergegevens.

Voordelen:

Snelle code-ontwikkeling aan het begin

Nadelen:

Grote moeilijkheden bij onderhoud, onboarding van nieuwe medewerkers is sterk vertraagd
Fouten zijn moeilijk op te sporen als de typen van parameters verwisseld zijn.

Positief geval

Alle publieke functies hebben een uitgebreide docstring en correcte type hints, waardoor IDE's en analyzers snel typefouten kunnen vinden en automatisch documentatie voor de API kunnen genereren.