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 dan 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 gebruikgemaakt 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 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 staan tussen drie dubbele aanhalingstekens en hebben doorgaans een vaste structuur:1 De eerste regel van de docstring geeft een korte samenvatting, 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. Je kunt de documentatie opvragen met de help()-functie. Zo vraag je bijvoorbeeld de documentatie van onderstaande functie op met help(integers_up_to). Dat geeft het resultaat zoals gegeven (druk op ).

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

Je zult misschien niet altijd de help()-functie gebruiken, 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 en handvaten 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 de docstring generator autoDocstring kunt gebruiken. Kies daarvoor in de linkerkantlijn het goede icoon voor extensions en selecteer dan de extensie autoDocstring. Zoek in de documentatie op hoe je automatisch (een deel van) de docstring kunt genereren.

Projecttraject

  • autodocstring

Wanneer je voor de functie integers_up_to() de docstring generator gebruikt, krijg je 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 kun je gemakkelijk de docstring invullen. Je kunt met Tab naar het volgende veld om de docstring snel in te vullen, zolang je niet op Esc drukt. 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 bij te werken als je een functie aanpast. Klik hier

Pythondaq: docstrings

Alle code van je pythondaq-applicatie voorzie je van docstrings. Je hebt in de Google Python Style Guide3 opgezocht waar je docstrings moet plaatsen.

Daarna test je het gemak van docstrings uit. Je bent aan het werk in je model (diode_experiment.py) en ziet dat er gebruik wordt gemaakt van een method get_input_voltage() die in de controller (arduino_device.py) staat. Je vraagt je ineens af wat deze method ook al weer doet. Voorheen ging je dan naar de controller en scrolde je naar de method get_input_voltage(). Maar tegenwoordig heb je overal docstrings geschreven. Je blijft daarom in het model, je houd je muis bij get_input_voltage() en je ziet daar je fantastische omschrijving van de method die in de controller staat!

Pseudo-code 

# class ArduinoVISADevice
    """Summary of class

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

(ECPC) > python arduino_device.py

Checkpunten:

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

Projecttraject:

  • Pythondaq: docstrings
  • Pythondaq: uv
  • Pythondaq: src-layout
  • 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 documentatiegenerator en Material for MkDocs is daar de meestgebruikte uitbreiding op. Het wordt veel gebruikt om documentatie te schrijven voor softwareprojecten. Een paar voorbeelden zijn de website van de Accelerators and Beam Physics Computing groep op CERN5 en de nieuwe Textual-bibliotheek6 om zogenaamde text-based 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/. ↩