Hoe documenteer je Python-code

Ben je net begonnen met Python en wil je meer leren? Volg dan DataCamp's cursus Intermediate Python.

Het belang van documentatie voor je project

Documentatie is een essentieel onderdeel van elk project waar je aan werkt, ongeacht de programmeertaal die je gebruikt. Een project met een applicatie die uit verschillende API’s bestaat en volop in gebruik is, maar zónder documentatie, wordt als onvolledig beschouwd. Stel je even voor dat je als developer een project wilt repliceren of een onderdeel ervan wilt gebruiken zonder dat er documentatie is. Waarschijnlijk kost het je veel moeite om het te integreren in je eigen architectuur.

Betere documentatie maakt je project succesvoller, omdat je wilt dat de wereld het kan gebruiken zodra je het deelt, zeker als het om een open-sourceproject gaat. Je wilt ook dat de community bijdraagt aan je project en het verbetert.

De bekende bedenker van de programmeertaal Python zegt: Code wordt vaker gelezen dan geschreven. Deze uitspraak onderstreept hoe belangrijk documentatie is als anderen je code of project gaan implementeren.

Stel, je werkt bij XYZ en je zit in je opzegtermijn. Je manager wil dat je het project overdraagt aan een collega. Je kunt hem een KT (knowledge transfer) geven, maar wat als je collega er niet in slaagt een van de scripts succesvol uit te voeren? Daar kunnen allerlei redenen voor zijn: misschien komen de binaries waarop jouw code draait niet overeen met de binaries van het huidige besturingssysteem.

Wat is documentatie precies?

Documentatie bestaat uit meerdere onderdelen. Het moet logisch rond die onderdelen worden opgebouwd en eraan voldoen om als goede documentatie te gelden.

Op abstract niveau zijn de componenten:

• Ervoor zorgen dat de codebase van je project goed van commentaar is voorzien.

• Voldoen aan de PEP 8-codestandaarden van Python.

• Concrete tutorials over hoe het project is opgebouwd, vooral als het een open-sourceproject is met een leerdoel.

• Een handleiding voor het installeren van de benodigde packages en modules die zijn gebruikt om de software te bouwen, plus een technische specificatiesheet als het project ook hardware bevat. Bijvoorbeeld: hoe je anaconda, TensorFlow, Keras, enz. installeert.

• Meerdere verslagen van de voortgang van het project per tijdstap, die hebben bijgedragen aan de succesvolle implementatie van de software.

• Referentiemateriaal met een technische beschrijving van de technologiestack die tijdens de ontwikkelfase is gebruikt.

• Het architectuurontwerp van het project of de softwareoplossing.

Dit zijn slechts enkele onderdelen die je kunt aantreffen in een goed gestructureerd en compleet ogend document. Het is belangrijk om deze componenten gescheiden te houden; dat maakt het ook makkelijker om de documentatie in de toekomst te onderhouden.

Een voorbeeld van uitgebreide documentatie met de meeste van de besproken onderdelen ziet er ongeveer zo uit als hieronder:

Veel mensen halen commentaar en documenteren door elkaar en vinden het hetzelfde. Commentaar beschrijft je code voor de gebruiker, de maintainer en voor jezelf als naslag. Commentaar werkt alleen op codeniveau en is te zien als een subset van documentatie. Met commentaar help je de lezer om:

• je code te begrijpen,
• het zelfverklarend te maken, en
• het doel en ontwerp te doorgronden.

Onthoud dat, omdat Python de PEP 8-codestandaarden volgt, zelfs commentaar aan die standaarden moet voldoen. In de officiële Python-documentatie staat dat voor langere tekstblokken met minder structurele beperkingen (docstrings of commentaar) de regellengte beperkt moet blijven tot 72 tekens.

Om te controleren of je code aan de PEP 8-standaarden voldoet, kun je de Python-module pylint gebruiken. Met deze module kun je de tekenlimiet voor commentaar en alle andere codelijnen aanpassen.

Laten we een paar voorbeelden bekijken.

• Omschrijving bij importeren van een module

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Omschrijving bij variabeledefinitie

n_classes = 10 # MNIST total classes (0-9 digits)

Voor een diepgaander begrip van commentaar en de do’s & don’ts, bekijk dit handige artikel.

Laten we nu leren hoe docstrings kunnen helpen bij het documenteren van de codebase van je project.

Docstrings voor het documenteren van Python-code

Een Python-docstring is een documentatiestring: een stringliteral die voorkomt in de definitie van een class, module, functie of methode, en als eerste statement wordt geschreven. Docstrings zijn toegankelijk via het doc-attribuut (__doc__) van elk Python-object, en ook via de ingebouwde functie help().

Docstrings zijn ook heel geschikt om de functionaliteit van grotere delen van de code te begrijpen, oftewel het algemene doel van een class, module of functie. Commentaar daarentegen gebruik je bij code, statements en expressies, die meestal klein zijn. Het is beschrijvende tekst die een programmeur vooral voor zichzelf schrijft om te weten wat een regel code of expressie doet, en ook voor de developer die aan het project wil bijdragen. Het is essentieel: het documenteren van je code helpt je bij het schrijven van schone code en goed gestructureerde programma’s. Hoewel al genoemd, bestaan er geen vaste standaarden en regels voor.

Er zijn twee vormen om een docstring te schrijven: one-line docstrings en multi-line docstrings. Dit zijn de vormen die data scientists/programmeurs in hun projecten gebruiken.

• De one-line docstrings passen in één regel. Je kunt enkele of dubbele driedubbele aanhalingstekens gebruiken; openings- en sluittekens moeten gelijk zijn. Bij one-line docstrings staan de sluittekens op dezelfde regel als de opening. De standaardconventie is om driedubbele dubbele aanhalingstekens te gebruiken.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Multi-line docstrings bevatten dezelfde stringliteral als one-line docstrings, maar worden gevolgd door een lege regel en vervolgens de beschrijvende tekst.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Uit de bovenstaande tabel kiezen we Pydoc als een van de docstringformaten en verkennen we het kort.

Zoals je hebt gezien, zijn docstrings toegankelijk via het ingebouwde Python-attribuut __doc__ en de functie help(). Je kunt ook gebruikmaken van de ingebouwde module Pydoc, die qua features en functionaliteit sterk verschilt van het doc-attribuut en de help-functie.

Pydoc is een tool die handig is als je code wilt delen met collega’s of open source wilt maken. Je richt je dan op een veel groter publiek. Pydoc kan webpagina’s genereren op basis van je Python-documentatie en ook een webserver starten.

Laten we kijken hoe het werkt.

De makkelijkste en meest praktische manier om de Pydoc-module te draaien, is als script. In een Jupyter Lab-cel gebruik je daarvoor het uitroepteken (!).

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Zoals je in de bovenstaande output ziet, is het eerste gebruik van Pydoc het tonen van tekstuele documentatie over een functie, module, class, enz. Laten we zien hoe je dat beter kunt benutten dan met de help-functie.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Laten we nu de documentatie van glob opvragen met de help-functie.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Zoals je ziet, krijg je een NameError omdat glob niet is gedefinieerd. Om de help-functie te gebruiken voor documentatie moet je de module eerst importeren. Dat hoeft niet bij Pydoc.

Laten we de interessantste feature van de Pydoc-module verkennen: Pydoc draaien als webservice.

Hiervoor draai je Pydoc opnieuw als script, maar met het argument -b. Dit start een HTTP-server op een willekeurige vrije poort en opent een webbrowser om de documentatie interactief te bekijken. Dit is handig als er meerdere services op je systeem draaien en je niet meer weet welke poort vrij is.

!python -m pydoc -b

^C

Zodra je de bovenstaande cel uitvoert, gaat er een nieuw venster open op een willekeurig poortnummer en ziet de webbrowser eruit zoals hieronder.

Laten we de documentatie bekijken van de module h5py, een bestandsformaat voor het opslaan van gewichten van neurale netwerkarchitecturen.

Essentials bij het documenteren van Python-projecten

Ongeacht doel, visie en projectdoel blijft de documentatie van elk project grotendeels hetzelfde. Een project kan in de volgende categorieën vallen:

• Privé (persoonlijk) project: bijvoorbeeld voor het opbouwen van je portfolio of als freelancer met een GitHub-repository.

• Collaboratieve (team)projecten: bijvoorbeeld een project binnen je organisatie of meedoen aan een Kaggle-competitie.

• Open-sourceprojecten: gericht op delen met een breed publiek. Verwacht wordt samenwerking, bijdragen en langdurige onderhoudbaarheid van codebase en documentatie.

Hoewel de drie categorieën verschillende visies hebben, kan het sjabloon voor documentatie voor alle soorten projecten worden hergebruikt.

Stel, je werkt aan een open-sourceproject en je moet er een GitHub-repository voor maken met gedetailleerde, regelmatig bijgewerkte documentatie. Houd dan het volgende in gedachten:

• Requirements-bestand: Dit vergeten auteurs vaak, maar het is heel belangrijk. Het helpt gebruikers je code snel te reproduceren. Meestal is het een tekstbestand met alle packages en modules plus de bijbehorende versies die in het project zijn gebruikt. Requirements kunnen ook in de Readme worden genoemd, maar een apart bestand is handiger: de gebruiker kan het dan met een pip-commando draaien, waarna alle dependencies op hun systeem worden geïnstalleerd.

• Readme: De Readme is meestal in markdown en vormt de ruggengraat van veel projecten. Een samenvatting van het project, de features en het doel, bij voorkeur met een mooi logo. Neem instructies op voor installatie of gebruik. Voeg daarnaast belangrijke wijzigingen sinds de vorige versie toe. Testscripts of een korte rondleiding om de code succesvol te draaien in de Readme geven de gebruiker meer vertrouwen om met je project aan de slag te gaan. Je kunt ook potentiële problemen voor gebruikers benoemen.

• Hoe samen te werken: Belangrijk, zeker bij open source. Beschrijf hoe nieuwe bijdragers kunnen meewerken: nieuwe features ontwikkelen, bekende bugs fixen, documentatie aanvullen, nieuwe tests toevoegen of issues melden. Samenwerkers kunnen zelfs een v2.0 uitbrengen en het project naar een hoger niveau tillen.

• Licentie: Een platte-tekstbestand met de licentie van je project. Zeker cruciaal voor open source: licenties als Boost, Apache, MIT, enz. Dit informeert de gebruiker of het project commercieel gebruikt mag worden en in welke mate.

• Taaktoewijzing: Werk je aan een gedeeld project zoals Kaggle, definieer dan de taken per teamlid en de voortgang. Dit helpt de totale voortgang te bewaken.

• Herbruikbaarheid van het framework: Van vitaal belang in een gedeeld project (zoals Kaggle), zodat teamgenoten kunnen hergebruiken wat jij hebt gebouwd. Dat bespaart veel tijd. Voorbeelden: een datapreprocessing-pijplijn, een script voor cross-validatie, enz.

Een sterk aanbevolen documentatie die zeer goed gestructureerd is en een uitstekend voorbeeld van een open-sourceproject vormt, is de GitHub-repository van huggingface transformers.

Conclusie

Gefeliciteerd met het afronden van de tutorial.

Een goede oefening is om de Pydoc-module verder te verkennen, en ook andere Python-docstringformaten zoals Epydoc en Google docstrings, en te ontdekken hoe ze van elkaar verschillen.

Stel gerust vragen over deze tutorial in de reacties hieronder.

Referenties:

• Docstrings in Python

Ben je net begonnen met Python en wil je meer leren? Volg dan DataCamp's cursus Intermediate Python.