Dobrý kód obsahuje komentáre, ktoré mu pomáhajú porozumieť, a reťazce dokumentov v tom môžu hrať hlavnú úlohu.

Bez náležitej dokumentácie môže byť ťažké pochopiť, udržiavať a ladiť váš kód. V Pythone môžete použiť docstring na poskytnutie stručných popisov a príkladov fungovania kódu.

Čo sú to docstringy?

Docstrings sú reťazce, ktoré môžete pridať do svojho kódu Python, aby ste vysvetlili, čo robí a ako ho používať. Úsek kódu môže byť a Funkcia Python, modul alebo trieda.

Docstringy vyzerajú veľmi podobne ako štandardné komentáre Pythonu, ale majú určité rozdiely. Komentáre Pythonu poskytujú vývojárom ďalšie informácie o vnútornom fungovaní kódu, ako sú podrobnosti o implementácii alebo upozornenia, ktoré treba mať na pamäti pri rozširovaní kódu.

Na druhej strane, reťazce dokumentov väčšinou poskytujú informácie používateľom kódu, ktorí nemusia nevyhnutne poznať podrobnosti o jeho implementácii, ale musia pochopiť, čo robí a ako ho používať.

Ako písať reťazce dokumentov

Na začiatok bloku kódu, ktorý chcete zdokumentovať, zvyčajne zahrniete reťazce dokumentov. Musíte ich uzavrieť do troch úvodzoviek (). Môžete napísať jednoriadkové dokumentačné reťazce alebo viacriadkové dokumentačné reťazce.

instagram viewer

Jednoriadkové dokumentačné reťazce sú vhodné pre jednoduchý kód, ktorý nevyžaduje veľa dokumentácie.

Nižšie je uvedený príklad funkcie nazývanej multiply. Dokumentačný reťazec vysvetľuje, že funkcia násobenia vezme dve čísla, vynásobí ich a vráti výsledok.

defmnožiť(a, b):
Vynásobí dve čísla a vráti výsledok
vrátiť a * b

Použite viacriadkové reťazce dokumentov pre zložitejší kód, ktorý si vyžaduje podrobnú dokumentáciu.

Zvážte nasledujúcu triedu automobilov:

triedaAuto:

 A triedazastupujúciaautoobjekt.
 Vlastnosti:
 najazdené kilometre (float): Aktuálny počet najazdených kilometrov automobilu.


 Metódy:
 riadiť (míle): Riadi auto pre určený počet kilometrov.


def__init__(ja, najazdené kilometre):
 self.najazdené kilometre = najazdené kilometre


defriadiť(ja, míle):

 Riadi auto pre určený počet kilometrov.


 Args:
 míle (float): Počet míľ, ktoré treba prejsť.
 Vrátenie:
žiadne

 vlastný počet najazdených kilometrov += míle

Dokumentačný reťazec pre vyššie uvedenú triedu popisuje, čo trieda predstavuje, jej atribúty a metódy. Medzitým dokumentačné reťazce pre metódu jednotky poskytujú informácie o tom, čo metóda robí, aké argumenty očakáva a čo vracia.

To uľahčuje každému, kto pracuje s touto triedou, pochopiť, ako ju používať. Medzi ďalšie výhody používania dokumentačných reťazcov patria:

  • Udržateľnosť kódu: Poskytnutím jasného popisu toho, ako kód funguje, reťazce dokumentov pomáhajú vývojárom upravovať a aktualizovať kód bez zavádzania chýb.
  • Jednoduchšia spolupráca: Keď niekoľko vývojárov spolupracuje na rovnakej kódovej základni – napríklad s Nástroj na živé zdieľanie Visual Studio—docstringy umožňujú vývojárom dokumentovať kód konzistentne, aby mu každý v tíme porozumel.
  • Vylepšená čitateľnosť kódu: Docstring poskytuje súhrn na vysokej úrovni o tom, čo kód umožňuje ktokoľvek číta kód, aby rýchlo pochopil jeho účel bez toho, aby prešiel celým kódom blokovať.

Docstring formáty

Dobrý dokumentačný reťazec by mal popisovať, čo robí časť kódu, argumenty, ktoré očakáva, a v prípade potreby podrobnosti o implementácii. Mal by zahŕňať najmä všetky okrajové prípady, o ktorých by mal vedieť každý, kto používa kód.

Základný formát dokumentačného reťazca má nasledujúce časti:

  • Súhrnný riadok: Jednoriadkový súhrn toho, čo kód robí.
  • Argumenty: Informácie o argumentoch, ktoré funkcia očakáva, vrátane ich dátových typov.
  • Návratová hodnota: Informácie o návratovej hodnote funkcie vrátane jej dátového typu.
  • Zvyšuje (voliteľné): Informácie o akýchkoľvek výnimkách, ktoré môže funkcia vyvolať.

Toto je len základný formát, pretože existujú aj iné formáty, z ktorých si môžete vybrať základ pre svoje dokumentačné reťazce. Najpopulárnejšie sú Epytext, reStructuredText (tiež známy ako reST), NumPy a dokumentačné reťazce Google. Každý z týchto formátov má svoju vlastnú syntax, ako je uvedené v nasledujúcich príkladoch:

Epytext

Dokumentačný reťazec, ktorý nasleduje vo formáte Epytext:

defmnožiť(a, b):

 Vynásobte dve čísla spolu.
 @param a: Prvé číslo, ktoré sa má vynásobiť.
 @type a: int
 @param b: Druhé číslo, ktoré sa má vynásobiť.
 @typ b: int
 @return: Súčin dvoch čísel.
 @rtype: int

vrátiť a * b

reStructuredText (reST)

Dokumentačný reťazec, ktorý má formát reST:

defmnožiť(a, b):

 Vynásobte dve čísla spolu.
 :param a: Prvé číslo, ktoré sa má vynásobiť.
 :type a: int
 :param b: Druhé číslo, ktoré sa má vynásobiť.
 :typ b: int
 :vrátiť: Súčin dvoch čísel.
 :rtype: int

vrátiť a * b

NumPy

Dokumentačný reťazec, ktorý sleduje formát NumPy:

defmnožiť(a, b):

 Vynásobte dve čísla spolu.
 Parametre

 a: int
 Prvé číslo, ktoré sa má vynásobiť.
 b: int
 Druhé číslo na vynásobenie.
 Návraty

 int
 Súčin dvoch čísel.

vrátiť a * b

Google

Dokumentačný reťazec vo formáte Google:

defmnožiť(a, b):

 Vynásobte dve čísla spolu.
 Args:
 a (int): Prvé číslo, ktoré sa má vynásobiť.
 b (int): Druhé číslo, ktoré sa má vynásobiť.
 Vrátenie:
 int: Súčin dvoch čísel.

vrátiť a * b

Hoci všetky štyri formáty docstring poskytujú užitočnú dokumentáciu pre funkciu násobenia, formáty NumPy a Google sú ľahšie čitateľné ako formáty Epytext a reST.

Ako zahrnúť testy do reťazcov dokumentov

Pomocou modulu doctest môžete do svojich reťazcov docstringov zahrnúť príklady testovania. Modul doctest hľadá v dokumente text, ktorý vyzerá ako interaktívne relácie Pythonu, a potom ich vykoná, aby overil, či fungujú tak, ako majú.

Ak chcete použiť doctests, zahrňte vzorové vstupy a očakávané výstupy do docstringu. Nižšie je uvedený príklad, ako by ste to urobili:

defmnožiť(a, b):

 Vynásobte dve čísla spolu.
 Parametre

 a: int
 Prvé číslo, ktoré sa má vynásobiť.
 b: int
 Druhé číslo na vynásobenie.


 Návraty

 int
 Súčin dvoch čísel.
 Príklady

 >>> vynásobiť(2, 3)
6
 >>> vynásobiť(0, 10)
0
 >>> vynásobiť(-1, 5)
-5

vrátiť a * b

The Príklady časť obsahuje tri volania funkcií s rôznymi argumentmi a pre každé špecifikuje očakávaný výstup. Keď spustíte modul doctest, ako je uvedené nižšie, vykoná sa príklady a porovná skutočný výstup s očakávaným výstupom.

python -m doctest multiply.py

Ak existujú nejaké rozdiely, modul doctest ich ohlási ako zlyhania. Použitie doctests s docstringmi, ako je tento, vám pomôže overiť, či kód funguje podľa očakávania. Upozorňujeme, že doctests nenahrádzajú komplexnejšie jednotkové testy a integračné testy pre váš kód Python.

Ako generovať dokumentáciu z reťazcov dokumentov

Naučili ste sa základy používania docstringov na dokumentovanie vášho Python kódu a dôležitosť vysokokvalitnej dokumentácie. Aby ste to posunuli ďalej, možno budete chcieť vygenerovať dokumentáciu pre svoje moduly a funkcie z ich príslušných dokumentačných reťazcov.

Jeden z najpopulárnejších generátorov dokumentácie, ktorý môžete použiť, je Sphinx. V predvolenom nastavení podporuje formát reST docstring, ale môžete ho nakonfigurovať tak, aby fungoval s formátom Google alebo NumPy.