Hur man dokumenterar Python-kod med hjälp av Docstrings

Utan korrekt dokumentation kan det vara svårt att förstå, underhålla och felsöka din kod. I Python kan du använda docstrings för att ge kortfattade beskrivningar och exempel på hur koden fungerar.

Vad är Docstrings?

Docstrings är strängar som du kan lägga till i din Python-kod för att förklara vad den gör och hur du använder den. Kodbiten kan vara en Python funktion, en modul eller en klass.

Docstrings ser mycket ut som vanliga Python-kommentarer, men de har vissa skillnader. Python-kommentarer tillhandahåller ytterligare information till utvecklare om kodens inre funktion, såsom implementeringsdetaljer eller varningar att tänka på när du utökar koden.

Å andra sidan ger docstrings mest information till användare av koden som kanske inte nödvändigtvis behöver känna till dess implementeringsdetaljer men behöver förstå vad den gör och hur man använder den.

Hur man skriver Docstrings

Du inkluderar vanligtvis docstrings i början av kodblocket du vill dokumentera. Du måste bifoga dem inom tredubbla citattecken (). Du kan skriva en-rads docstrings eller multi-line docstrings.

Enrads docstrings är lämpliga för enkel kod som inte kräver mycket dokumentation.

Nedan är ett exempel på en funktion som kallas multiplicera. Dokstringen förklarar att multipliceringsfunktionen tar två tal, multiplicerar dem och returnerar resultatet.

defmultiplicera(a, b):
Multiplicerar två tal och returnerar resultatet
lämna tillbaka a * b

Använd flerradiga docstrings för mer komplex kod som behöver detaljerad dokumentation.

Tänk på följande bilklass:

klassBil:

 A klassrepresenterarabilobjekt.
 Attribut:
 mileage (float): Bilens nuvarande körsträcka.
 Metoder:
 drive (miles): Kör bilen för det angivna antalet mil.

def__i det__(själv, körsträcka):
 self.mileage = mileage
defkör(själv, miles):

 Kör bilen för det angivna antalet mil.
 Args:
 miles (float): Antalet miles att köra.
 Returnerar:
Ingen

 self.mileage += miles

Dokstringen för ovanstående klass beskriver vad klassen representerar, dess attribut och dess metoder. Samtidigt ger docstrings för drivmetoden information om vad metoden gör, argumenten den förväntar sig och vad den returnerar.

Detta gör det lättare för alla som arbetar med den här klassen att förstå hur man använder den. De andra fördelarna med att använda docstrings inkluderar:

• Kodunderhållbarhet: Genom att ge en tydlig beskrivning av hur koden fungerar hjälper docstrings utvecklare att ändra och uppdatera koden utan att införa fel.
• Enklare samarbete: När flera utvecklare samarbetar på samma kodbas – till exempel med Visual Studio live share-verktyg—docstrings tillåter utvecklare att dokumentera koden konsekvent så att alla i teamet kan förstå den.
• Förbättrad kodläsbarhet: Docstrings ger en sammanfattning på hög nivå av vad kod gör som tillåter alla som läser koden för att snabbt förstå dess syfte utan att gå igenom hela koden blockera.

Docstring-format

En bra docstring bör beskriva vad en kod gör, argumenten den förväntar sig och implementeringsdetaljer om det behövs. Det bör särskilt inkludera eventuella kantfall som alla som använder koden bör vara medvetna om.

Ett grundläggande docstring-format har följande avsnitt:

• Sammanfattningsrad: En enrads sammanfattning av vad koden gör.
• Argument: Information om de argument som funktionen förväntar sig inklusive deras datatyper.
• Returvärde: Information om funktionens returvärde inklusive dess datatyp.
• Höjningar (valfritt): Information om eventuella undantag som funktionen kan höja.

Detta är bara ett grundläggande format eftersom det finns andra format du kan välja för att basera dina docstrings. De mest populära är Epytext, reStructuredText (även känd som reST), NumPy och Google docstrings. Vart och ett av dessa format har sin egen syntax som visas i följande exempel:

Epytext

En docstring som följer Epytext-formatet:

defmultiplicera(a, b):

 Multiplicera två tal tillsammans.
 @param a: Det första talet som ska multipliceras.
 @typ a: int
 @param b: Det andra talet som ska multipliceras.
 @typ b: int
 @return: Produkten av de två talen.
 @rtype: int

lämna tillbaka a * b

reStructuredText (reST)

En docstring som följer reST-formatet:

defmultiplicera(a, b):

 Multiplicera två tal tillsammans.
 :param a: Det första talet som ska multipliceras.
 :typ a: int
 :param b: Det andra talet som ska multipliceras.
 :typ b: int
 :lämna tillbaka: Produkten av de två talen.
 :rtype: int

lämna tillbaka a * b

NumPy

En docstring som följer NumPy-formatet:

defmultiplicera(a, b):

 Multiplicera två tal tillsammans.
 Parametrar

 a: int
 Den första siffran att multiplicera.
 b: int
 Den andra siffran att multiplicera.
 Returnerar

 int
 Produkten av de två talen.

lämna tillbaka a * b

Google

En docstring som följer Googles format:

defmultiplicera(a, b):

 Multiplicera två tal tillsammans.
 Args:
 a (int): Det första talet som ska multipliceras.
 b (int): Det andra talet som ska multipliceras.
 Returnerar:
 int: Produkten av de två talen.

lämna tillbaka a * b

Även om alla fyra docstring-formaten ger användbar dokumentation för multiplikationsfunktionen, är NumPy- och Google-formaten lättare att läsa än Epytext- och reST-formaten.

Hur man inkluderar tester i Docstrings

Du kan inkludera testexempel i dina docstrings med hjälp av doctest-modulen. Doktestmodulen söker i dokumentsträngen efter text som ser ut som interaktiva Python-sessioner och kör dem sedan för att verifiera att de fungerar som de ska.

För att använda doctests, inkludera exempelingångarna och förväntade utgångarna i docstringen. Nedan är ett exempel på hur du skulle göra det:

defmultiplicera(a, b):

 Multiplicera två tal tillsammans.
 Parametrar

 a: int
 Den första siffran att multiplicera.
 b: int
 Den andra siffran att multiplicera.
 Returnerar

 int
 Produkten av de två talen.
 Exempel

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

lämna tillbaka a * b

De Exempel avsnittet innehåller tre funktionsanrop med olika argument och specificerar förväntad utdata för varje. När du kör doctest-modulen som visas nedan, kommer den att köra exemplen och jämföra den faktiska utmatningen med den förväntade utmatningen.

python -m doctest multiply.py

Om det finns några skillnader rapporterar doctest-modulen dem som misslyckanden. Att använda doctests med docstrings som denna hjälper dig att verifiera att koden fungerar som förväntat. Observera att doktest inte är en ersättning för mer omfattande enhetstester och integrationstester för din Python-kod.

Hur man genererar dokumentation från Docstrings

Du har lärt dig grunderna i att använda docstrings för att dokumentera din Python-kod och vikten av högkvalitativ dokumentation. För att ta det upp ett snäpp kanske du vill generera dokumentation för dina moduler och funktioner från deras respektive docstrings.

En av de mest populära dokumentationsgeneratorerna du kan använda är Sphinx. Det stöder reST docstring-format som standard men du kan konfigurera det för att fungera med Google- eller NumPy-formatet.