Skip to content

Docstrings

Documentatie is vaak een onderschoven kindje, maar is ontzettend belangrijk. Als je zelf informatie opzoekt over bijvoorbeeld een voor jou onbekende Pythonbibliotheek dan vind je het heel fijn als er een duidelijke tutorial is. Als je code schrijft die ook door andere mensen gebruikt moet worden is documentatie nodig. Als de code langer mee moet gaan dan zeg een paar weken, dan helemaal. Want over een paar weken ben jij zelf een ander persoon. Hoe vervelend het ook is, code die je nota bene zelf geschreven hebt is over een paar weken niet meer glashelder. Je zult dan moeten uitzoeken hoe je ook alweer iets hebt gedaan of wat de gedachte erachter was.

Tot nu toe heb je waarschijnlijk gebruik gemaakt van #stukjes commentaar om duidelijk te maken wat je code doet. Maar als je de applicatie aan het gebruiken bent en je wilt weten wat een bepaalde functie eigenlijk doet, moet je dus de code induiken op zoek naar de betreffende functie. Met docstrings — documentatiestrings — is dat verleden tijd. De documentatie over een functie kan automatisch gegenereerd worden vanuit je code met behulp van de docstring. Docstrings staat tussen 3 dubbele aanhalingstekens en hebben doorgaans een vaste structuur:1

integers_up_to.py 
def integers_up_to(number):
    """List integers up to a given number.

    Args:
        number (int): list integers up to this number

    Returns:
        list: containing the integers
    """
    if number > 1:
        return list(range(1, number))
    else:
        return []


help(integers_up_to)

(ecpc) > python integers_up_to.py

De eerste regel geeft een korte samenvatting weer, na de witregel komt een langere samenvatting. Met Args: worden alle argumenten opgesomd die aan de functie worden meegegeven en Returns: geeft aan wat de functie teruggeeft. We kunnen de documentatie van deze functie opvragen met: help(integers_up_to). Dat geeft resultaat zoals hierboven gegeven (druk op ).

Je zult niet altijd de help() functie gebruiken misschien, maar gebruik zoveel mogelijk docstrings — ze helpen ook enorm als je de code leest. Het is extra werk maar het verdient zich dubbel en dwars terug. Je hoeft geen proza te schrijven, maar wees duidelijk. Lees voor meer voorbeelden bijvoorbeeld de Google Python Style Guide.3

Docstring generator

Om het gemakkelijker te maken om docstrings ook écht te gaan schrijven, zijn er docstring generators ontwikkeld. Voor Visual Studio Code is er de extensie autoDocstring - Python Docstring Generator.4

Autodocstring

Kijk in Visual Studio Code bij extensions hoe je AutoDocstring kunt gebruiken. Kies daarvoor in de linkerkantlijn het goede icoon voor extensions en selecteer dan de autoDocstring extensie. Zoek in de documentatie naar hoe je automatisch (een deel van) de docstring genereert.

Wanneer we voor de functie integers_up_to() de docstring generator gebruiken, krijgen we het volgende: 

def integers_up_to(number):
"""_summary_

Args:
    number (_type_): _description_

Returns:
    _type_: _description_
"""
if number > 1:
    return list(range(1, number))
else:
    return []

Zo kunnen we gemakkelijk alles gaan invullen. Zo lang je niet op Esc drukt maar gewoon je tekst typt kun je met Tab naar het volgende veld en zo de docstring snel invullen. Het is mooi als je daarna onder de summary nog een uitgebreidere uitleg geeft van een paar zinnen. Vergeet ook niet om de docstring zonodig weer bij te werken als je een functie aanpast.

Pythondaq: docstring

Alle code van je pythondaqapplicatie zijn voorzien van docstrings. Je bent aan het werk in je model script en ziet dat er gebruik wordt gemaakt van een method get_input_voltage() die in de controller staat. Je vraagt je ineens af wat deze method ook al weer doet. Voorheen ging je dan naar de controller en scrolde je naarget_input_voltage(). Maar tegenwoordig heb je overal docstrings geschreven, je blijft in het model-script, houd je muis bij get_input_voltage() en ziet daar je fantastische omschrijving van de method die in de controller staat!

Pseudo-code 

# class ArduinoVISADevice
    """Summary of class here.

    Longer class information...
    Longer class information...
    """
    ...
Testcode:
arduino_device.py 
if __name__ == "__main__":
    help(ArduinoVISADevice)

(ecpc) > python arduino_device.py

Checkpunten:

  • De controller, de model én de view zijn voorzien van docstrings.
  • Er staan docstrings bij onder andere alle functies, methods en classes.
  • De docstrings hebben een vaste structuur volgens de Google Python Style Guide.3.
  • De docstrings zijn volledig.
  • De docstrings bevat noodzakelijke en nuttige informatie.

Projecttraject:

  • Pythondaq: Docstring
  • Pythondaq: src-layout
  • Pythondaq: poetry
  • Pythondaq: test imports
  • Pythondaq: applicatie
Material for MkDocs

Documentatie met Material for MkDocs

Een bijkomend voordeel van docstrings is dat ze gebruikt kunnen worden om automatisch documentatie te genereren voor een heel project met behulp van bijvoorbeeld MkDocs of Sphinx.2 MkDocs is een documentatie generator en Material for MkDocs is daar de meestgebruikte uitbreiding op. Het wordt veel gebruikt om documentatie te schrijven voor software projecten. Een paar voorbeelden zijn bijvoorbeeld de website van de Accelerators and Beam Physics Computing groep op CERN5 of de nieuwe Textual bibliotheek6 om zogenaamde terminal user interfaces te maken, een tegenhanger van grafische interfaces. Behalve dat je vrij eenvoudig uitgebreide documentatie kunt schrijven kan MkDocs alle docstrings gebruiken om een referentie op te bouwen. De website voor de ECPC cursus is ook gebouwd met Material for MkDocs.

Het voert tijdens deze cursus te ver om veel aandacht te besteden aan MkDocs. Maar aangezien documentatie zo belangrijk is wilden we het toch noemen! Voor een uitgebreide tutorial, zie Build Your Python Project Documentation With MkDocs.7

  1. Die vaste structuur wordt niet door Python afgedwongen, maar is een goed gebruik. Er worden verschillende stijlen gebruikt. Eén van de meest gebruikte stijlen is door programmeurs van Google bedacht.3 ↩

  2. Sphinx is van oudsher de standaard documentatiegenerator voor Pythonprojecten. Maar Sphinx is al redelijk op leeftijd en gebruikt als tekstformaat niet het bekende en zeer populaire Markdown maar het steeds minder populaire Restructured Text. MkDocs wordt steeds meer gebruikt en Sphinx steeds minder. Toch zul je Sphinx nog veel tegenkomen bij projecten omdat het na al die jaren zeer veel features heeft en zeer stabiel is. ↩

  3. Google. Google python style guide. URL: https://google.github.io/styleguide/pyguide.html. ↩↩↩

  4. Nils Werner. Autodocstring - python docstring generator. URL: https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring. ↩

  5. Accelerators and Beam Physics Computing Group. Accelerators and beam physics computing. URL: https://abpcomputing.web.cern.ch. ↩

  6. Will McGugan and others. Textual. URL: https://textual.textualize.io. ↩

  7. Martin Breuss. Build your python project documentation with mkdocs. URL: https://realpython.com/python-project-documentation-with-mkdocs/. ↩