A Python-kód dokumentálása Docsstringek használatával

Megfelelő dokumentáció nélkül nehéz lehet a kód megértése, karbantartása és hibakeresése. A Pythonban a docstringek segítségével tömör leírásokat és példákat adhat a kód működésére.

Mik azok a dokstringek?

A docstringek olyan karakterláncok, amelyeket hozzáadhat Python-kódjához, hogy elmagyarázza, mit csinál és hogyan kell használni. A kódrészlet lehet a Python függvény, egy modul vagy egy osztály.

A docstringek nagyon hasonlítanak a szokásos Python-megjegyzésekhez, de vannak különbségek. A Python megjegyzések további információkat nyújtanak a fejlesztők számára a kód belső működéséről, például a megvalósítás részleteiről vagy a kód kiterjesztésekor szem előtt tartandó figyelmeztetésekről.

Másrészt a docstringek többnyire információt nyújtanak a kód felhasználóinak, akiknek nem feltétlenül kell ismerniük a megvalósítás részleteit, de meg kell érteniük, mit csinál és hogyan kell használni.

Hogyan írjunk Docsstringeket

A dokumentálni kívánt kódblokk elejére jellemzően docstringeket kell megadni. Ezeket háromszoros idézőjelbe kell tenni (). Írhat egysoros vagy többsoros dokumentumkarakterláncokat.

Az egysoros docstringek egyszerű kódokhoz alkalmasak, amelyek nem igényelnek sok dokumentációt.

Az alábbiakban egy példa látható a szorzás nevű függvényre. A docstring megmagyarázza, hogy a szorzás függvény két számot vesz fel, többszörözi őket, és visszaadja az eredményt.

defszaporodnak(a, b):
Két számot megszoroz, és visszaadja az eredményt
Visszatérés a * b

Használjon többsoros docstringeket az összetettebb, részletes dokumentációt igénylő kódokhoz.

Vegye figyelembe a következő autóosztályokat:

osztályAutó:

 A osztályképviselőaautótárgy.
 Tulajdonságok:
 futásteljesítmény (float): Az autó aktuális futásteljesítménye.
 Mód:
 meghajtó (mérföld): vezeti az autót számára a megadott számú mérföldet.

def__benne__(saját, futásteljesítmény):
 saját.kilométer = futásteljesítmény
defhajtás(én, mérföld):

 Az autót vezeti számára a megadott számú mérföldet.
 Args:
 mérföld (úszó): A megtehető mérföldek száma.
 Visszaküldések:
Egyik sem

 saját.futásteljesítmény += mérföld

A fenti osztályhoz tartozó docstring leírja, hogy az osztály mit képvisel, annak attribútumait és metódusait. Eközben a meghajtó metódus docstringjei információt nyújtanak arról, hogy a metódus mit csinál, milyen argumentumokat vár, és mit ad vissza.

Így mindenki, aki ezzel az osztállyal dolgozik, könnyebben megérti, hogyan kell használni. A docstringek használatának további előnyei a következők:

• Kód karbantarthatósága: A kód működésének egyértelmű leírásával a docstringek segítenek a fejlesztőknek a kód módosításában és frissítésében hibák nélkül.
• Könnyebb együttműködés: Ha több fejlesztő dolgozik ugyanazon a kódbázison – például a Visual Studio élő megosztási eszköz– A docstringek lehetővé teszik a fejlesztők számára, hogy következetesen dokumentálják a kódot, hogy a csapat minden tagja megértse.
• Továbbfejlesztett kód olvashatóság: A Docsstringek magas szintű összefoglalást adnak arról, hogy mit tesz lehetővé a kód, amely lehetővé teszi bárki elolvassa a kódot, hogy gyorsan megértse a célját anélkül, hogy a teljes kódon végigmenne Blokk.

Docstring formátumok

Egy jó dokumentumkarakterláncnak le kell írnia, hogy egy kódrészlet mit csinál, milyen argumentumokat vár el, és szükség esetén a megvalósítás részleteit. Különösen tartalmaznia kell minden olyan szélső esetet, amelyről a kódot használóknak tudniuk kell.

Egy alapvető dokumentumkarakterlánc-formátum a következő részekből áll:

• Összefoglaló sor: A kód működésének egysoros összefoglalása.
• Argumentumok: Információ a függvény által elvárt argumentumokról, beleértve azok adattípusait.
• Visszatérési érték: Információ a függvény visszatérési értékéről, beleértve az adattípust.
• Emelések (opcionális): Információ a függvény által esetlegesen felmerülő kivételekről.

Ez csak egy alapvető formátum, mivel más formátumok is választhatók a dokumentumkarakterláncok alapjául. A legnépszerűbbek az Epytext, a reStructuredText (más néven reST), a NumPy és a Google docstringek. Ezen formátumok mindegyikének saját szintaxisa van, amint azt a következő példák mutatják:

Epytext

Egy docstring, amely az Epytext formátumot követi:

defszaporodnak(a, b):

 Két számot összeszorozni.
 @param a: Az első szorzandó szám.
 @type a: int
 @param b: A második szám a szorzáshoz.
 @b típus: int
 @return: A két szám szorzata.
 @rtype: int

Visszatérés a * b

reStructuredText (reST)

Egy dokumentumkarakterlánc, amely a reST formátumot követi:

defszaporodnak(a, b):

 Két számot összeszorozni.
 :param a: Az első szorzandó szám.
 :type a: int
 :param b: A második szám a szorzáshoz.
 :b típus: int
 :Visszatérés: A két szám szorzata.
 :rtype: int

Visszatérés a * b

NumPy

Egy docstring, amely a NumPy formátumot követi:

defszaporodnak(a, b):

 Két számot összeszorozni.
 Paraméterek

 a: int
 Az első szorzandó szám.
 b: int
 A második szám a szorzáshoz.
 Visszatér

 int
 A két szám szorzata.

Visszatérés a * b

Google

Egy dokumentumkarakterlánc, amely a Google formátumát követi:

defszaporodnak(a, b):

 Két számot összeszorozni.
 Args:
 a (int): Az első szám, amelyet szorozni kell.
 b (int): A második szám a szorzáshoz.
 Visszaküldések:
 int: A két szám szorzata.

Visszatérés a * b

Bár mind a négy docstring formátum hasznos dokumentációt nyújt a szorzás funkcióhoz, a NumPy és a Google formátumok könnyebben olvashatók, mint az Epytext és a reST formátumok.

Hogyan lehet teszteket felvenni a Docsstringbe

A doctest modul segítségével tesztelési példákat is beilleszthet a docstringekbe. A doctest modul megkeresi a docstringben olyan szöveget, amely interaktív Python-munkameneteknek tűnik, majd végrehajtja azokat annak ellenőrzésére, hogy megfelelően működnek-e.

A doctestek használatához adja meg a minta bemeneteket és a várt kimeneteket a docstringben. Az alábbiakban egy példa látható, hogyan kell ezt megtenni:

defszaporodnak(a, b):

 Két számot összeszorozni.
 Paraméterek

 a: int
 Az első szorzandó szám.
 b: int
 A második szám a szorzáshoz.
 Visszatér

 int
 A két szám szorzata.
 Példák

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

Visszatérés a * b

A Példák szakasz három függvényhívást tartalmaz különböző argumentumokkal, és mindegyikhez megadja a várható kimenetet. Amikor az alábbiak szerint futtatja a doctest modult, az végrehajtja a példákat, és összehasonlítja a tényleges kimenetet a várt kimenettel.

python -m doctest multiply.py

Ha eltérések vannak, a doctest modul hibaként jelenti azokat. Az ehhez hasonló docstringekkel rendelkező doctestek segítségével ellenőrizheti, hogy a kód megfelelően működik-e. Vegye figyelembe, hogy a doctestek nem helyettesítik az átfogóbbakat egységtesztek és integrációs tesztek a Python-kódhoz.

Hogyan készítsünk dokumentációt a Docsstringből

Megtanulta a docstringek használatának alapjait a Python-kód dokumentálásához, valamint a jó minőségű dokumentáció fontosságát. A javításhoz érdemes lehet dokumentációt generálni a moduljaihoz és funkcióihoz a megfelelő dokumentumláncokból.

Az egyik legnépszerűbb dokumentumgenerátor a Sphinx. Alapértelmezés szerint támogatja a reST docstring formátumot, de beállíthatja úgy, hogy a Google vagy a NumPy formátummal működjön.