Python-code documenteren met behulp van Docstrings

Zonder de juiste documentatie kan het moeilijk zijn om uw code te begrijpen, te onderhouden en te debuggen. In Python kunt u docstrings gebruiken om beknopte beschrijvingen en voorbeelden te geven van hoe de code werkt.

Wat zijn Docstrings?

Docstrings zijn strings die je aan je Python-code kunt toevoegen om uit te leggen wat het doet en hoe je het moet gebruiken. Het stukje code kan een Python-functie, een module of een klas.

Docstrings lijken veel op standaard Python-opmerkingen, maar ze hebben enkele verschillen. Python-opmerkingen bieden ontwikkelaars aanvullende informatie over de interne werking van de code, zoals implementatiedetails of kanttekeningen waarmee rekening moet worden gehouden bij het uitbreiden van de code.

Aan de andere kant geven docstrings meestal informatie aan gebruikers van de code die niet per se de implementatiedetails hoeven te weten, maar wel moeten begrijpen wat het doet en hoe het te gebruiken.

Hoe Docstrings te schrijven

Meestal neemt u docstrings op aan het begin van het codeblok dat u wilt documenteren. U moet ze tussen driedubbele aanhalingstekens plaatsen (). U kunt eenregelige docstrings of meerregelige docstrings schrijven.

Eenregelige docstrings zijn geschikt voor eenvoudige code waarvoor niet veel documentatie nodig is.

Hieronder ziet u een voorbeeld van een functie genaamd vermenigvuldigen. De docstring legt uit dat de functie vermenigvuldigen twee getallen neemt, ze vermenigvuldigt en het resultaat retourneert.

defvermenigvuldigen(een, b):
Vermenigvuldigt twee getallen en geeft het resultaat
opbrengst een * b

Gebruik meerregelige docstrings voor complexere code waarvoor gedetailleerde documentatie nodig is.

Beschouw de volgende autoklasse:

klasAuto:

 A klasvertegenwoordigenAautovoorwerp.
 attributen:
 kilometerstand (float): De huidige kilometerstand van de auto.
 methoden:
 rijden (mijlen): Rijdt de auto voor het opgegeven aantal kilometers.

def__in het__(zelf, kilometerstand):
 self.mileage = kilometerstand
defdrijfveer(zelf, mijlen):

 Rijdt de auto voor het opgegeven aantal kilometers.
 argumenten:
 miles (float): Het aantal te rijden mijlen.
 Geeft terug:
Geen

 self.mileage += mijlen

De docstring voor de bovenstaande klasse beschrijft wat de klasse vertegenwoordigt, zijn attributen en zijn methoden. Ondertussen geven de docstrings voor de drive-methode informatie over wat de methode doet, de argumenten die het verwacht en wat het retourneert.

Dit maakt het gemakkelijker voor iedereen die met deze klasse werkt om te begrijpen hoe deze moet worden gebruikt. De andere voordelen van het gebruik van docstrings zijn:

• Onderhoudbaarheid van de code: door een duidelijke beschrijving te geven van hoe de code werkt, helpen docstrings ontwikkelaars de code aan te passen en bij te werken zonder fouten te introduceren.
• Gemakkelijkere samenwerking: wanneer verschillende ontwikkelaars samenwerken aan dezelfde codebasis, bijvoorbeeld met de Visual Studio-tool voor live delen—docstrings stellen ontwikkelaars in staat de code consistent te documenteren, zodat iedereen in het team deze kan begrijpen.
• Verbeterde leesbaarheid van code: Docstrings bieden een samenvatting op hoog niveau van wat code doet en toestaat iedereen die de code leest om snel het doel ervan te begrijpen zonder de hele code door te nemen blok.

Docstring-indelingen

Een goede docstring moet beschrijven wat een stuk code doet, de argumenten die het verwacht en indien nodig implementatiedetails. Het moet vooral alle randgevallen bevatten waarvan iedereen die de code gebruikt, op de hoogte moet zijn.

Een standaard docstring-indeling heeft de volgende secties:

• Samenvattingsregel: een samenvatting van één regel van wat de code doet.
• Argumenten: informatie over de argumenten die de functie verwacht, inclusief hun gegevenstypen.
• Retourwaarde: informatie over de retourwaarde van de functie, inclusief het gegevenstype.
• Verhoogt (optioneel): Informatie over eventuele uitzonderingen die de functie kan verhogen.

Dit is slechts een basisindeling, aangezien er andere indelingen zijn die u kunt kiezen om uw docstrings te baseren. De meest populaire zijn Epytext, reStructuredText (ook bekend als reST), NumPy en Google docstrings. Elk van deze indelingen heeft zijn eigen syntaxis, zoals te zien is in de volgende voorbeelden:

Epytekst

Een docstring die de Epytext-indeling volgt:

defvermenigvuldigen(een, b):

 Vermenigvuldig twee getallen met elkaar.
 @param a: Het eerste getal om te vermenigvuldigen.
 @type a: int
 @param b: Het tweede getal om te vermenigvuldigen.
 @type b: int
 @return: Het product van de twee getallen.
 @rtype: int

opbrengst een * b

reStructuredText (reST)

Een docstring die de reST-indeling volgt:

defvermenigvuldigen(een, b):

 Vermenigvuldig twee getallen met elkaar.
 :param a: Het eerste getal om te vermenigvuldigen.
 :typ a: int
 :param b: Het tweede getal om te vermenigvuldigen.
 :type b: int
 :opbrengst: Het product van de twee getallen.
 :rtype: int

opbrengst een * b

NumPy

Een docstring die de NumPy-indeling volgt:

defvermenigvuldigen(een, b):

 Vermenigvuldig twee getallen met elkaar.
 Parameters

 een: int
 Het eerste getal om te vermenigvuldigen.
 b: int
 Het tweede getal om te vermenigvuldigen.
 Geeft terug

 int
 Het product van de twee getallen.

opbrengst een * b

Google

Een docstring die de Google-indeling volgt:

defvermenigvuldigen(een, b):

 Vermenigvuldig twee getallen met elkaar.
 argumenten:
 a (int): Het eerste getal dat moet worden vermenigvuldigd.
 b (int): Het tweede getal om te vermenigvuldigen.
 Geeft terug:
 int: Het product van de twee getallen.

opbrengst een * b

Hoewel alle vier de docstring-formaten nuttige documentatie bieden voor de vermenigvuldigfunctie, zijn de NumPy- en Google-formaten gemakkelijker te lezen dan de Epytext- en reST-formaten.

Tests opnemen in de Docstrings

U kunt testvoorbeelden opnemen in uw docstrings met behulp van de doctest-module. De doctest-module zoekt in de docstring naar tekst die eruitziet als interactieve Python-sessies en voert deze vervolgens uit om te controleren of ze naar behoren werken.

Om doctests te gebruiken, neemt u de voorbeeldinvoer en verwachte uitvoer op in de docstring. Hieronder een voorbeeld van hoe je dat zou doen:

defvermenigvuldigen(een, b):

 Vermenigvuldig twee getallen met elkaar.
 Parameters

 een: int
 Het eerste getal om te vermenigvuldigen.
 b: int
 Het tweede getal om te vermenigvuldigen.
 Geeft terug

 int
 Het product van de twee getallen.
 Voorbeelden

 >>> vermenigvuldigen(2, 3)
6
 >>> vermenigvuldigen(0, 10)
0
 >>> vermenigvuldigen(-1, 5)
-5

opbrengst een * b

De Voorbeelden sectie bevat drie functieaanroepen met verschillende argumenten en specificeert de verwachte uitvoer voor elk. Wanneer u de doctest-module uitvoert zoals hieronder weergegeven, worden de voorbeelden uitgevoerd en wordt de daadwerkelijke uitvoer vergeleken met de verwachte uitvoer.

python -m doctest vermenigvuldigen.py

Als er verschillen zijn, rapporteert de doctest module deze als mislukkingen. Door doctests met docstrings zoals deze te gebruiken, kunt u controleren of de code werkt zoals verwacht. Merk op dat doctests geen vervanging zijn voor meer uitgebreide unit-tests en integratietests voor uw Python-code.

Documentatie genereren vanuit Docstrings

Je hebt de basis geleerd van het gebruik van docstrings om je Python-code te documenteren en het belang van hoogwaardige documentatie. Om nog een stap verder te gaan, wilt u misschien documentatie voor uw modules en functies genereren vanuit hun respectieve docstrings.

Een van de meest populaire documentatiegeneratoren die u kunt gebruiken, is Sphinx. Het ondersteunt standaard het reST docstring-formaat, maar u kunt het configureren om te werken met het Google- of NumPy-formaat.