Dobrý kód obsahuje komentáře, které mu pomáhají porozumět, a docstring v tom může hrát hlavní roli.

Bez řádné dokumentace může být obtížné porozumět, udržovat a ladit váš kód. V Pythonu můžete použít docstring k poskytnutí stručných popisů a příkladů toho, jak kód funguje.

Co jsou to docstringy?

Docstrings jsou řetězce, které můžete přidat do svého kódu Python, abyste vysvětlili, co dělá a jak jej používat. Část kódu může být a Funkce Python, modul nebo třída.

Docstrings vypadají hodně jako standardní komentáře Pythonu, ale mají určité rozdíly. Komentáře Pythonu poskytují vývojářům další informace o vnitřním fungování kódu, jako jsou podrobnosti o implementaci nebo upozornění, která je třeba mít na paměti při rozšiřování kódu.

Na druhou stranu, docstrings většinou poskytují informace uživatelům kódu, kteří nemusí nutně potřebovat znát detaily jeho implementace, ale potřebují rozumět tomu, co dělá a jak jej používat.

Jak psát řetězce dokumentů

Na začátek bloku kódu, který chcete dokumentovat, obvykle vkládáte řetězce dokumentů. Musíte je uzavřít do trojitých uvozovek (). Můžete psát jednořádkové docstring nebo víceřádkové docstring.

Jednořádkové docstringy jsou vhodné pro jednoduchý kód, který nevyžaduje mnoho dokumentace.

Níže je uveden příklad funkce nazvané multiply. Dokumentační řetězec vysvětluje, že funkce multiply vezme dvě čísla, vynásobí je a vrátí výsledek.

defnásobit(a, b):
Vynásobí dvě čísla a vrátí výsledek
vrátit se a * b

Pro složitější kód, který vyžaduje podrobnou dokumentaci, použijte víceřádkové docstring.

Zvažte následující třídu automobilů:

třídaAuto:

 A třídazastupujícíAautoobjekt.
 Atributy:
 najeté kilometry (float): Aktuální kilometrový výkon vozu.


 Metody:
 drive (míle): Řídí auto pro stanovený počet kilometrů.


def__init__(sebe, najeté kilometry):
 self.ujeto = najeté kilometry


defřídit(já, míle):

 Řídí auto pro stanovený počet kilometrů.


 Args:
 míle (float): Počet ujetých mil.
 Vrácení:
Žádný

 ujeté kilometry += mil

Dokumentační řetězec pro výše uvedenou třídu popisuje, co třída představuje, její atributy a metody. Mezitím dokumentační řetězce pro metodu drive poskytují informace o tom, co metoda dělá, jaké argumenty očekává a co vrací.

To usnadňuje každému, kdo pracuje s touto třídou, pochopit, jak ji používat. Mezi další výhody používání dokumentačních řetězců patří:

  • Udržovatelnost kódu: Poskytnutím jasného popisu toho, jak kód funguje, řetězce docstring pomáhají vývojářům upravovat a aktualizovat kód bez zavádění chyb.
  • Snazší spolupráce: Když několik vývojářů spolupracuje na stejné kódové základně – například s Nástroj pro živé sdílení Visual Studio—docstrings umožňují vývojářům konzistentně dokumentovat kód, aby mu každý v týmu porozuměl.
  • Vylepšená čitelnost kódu: Docstring poskytuje souhrnné shrnutí toho, co kód dělá, což umožňuje kdokoli čte kód, aby rychle pochopil jeho účel, aniž by procházel celý kód blok.

Docstring formáty

Dobrý dokumentační řetězec by měl popisovat, co část kódu dělá, argumenty, které očekává, a v případě potřeby podrobnosti o implementaci. Zejména by měl zahrnovat všechny okrajové případy, kterých by si měl být vědom každý, kdo používá kód.

Základní formát docstring má následující sekce:

  • Souhrnný řádek: Jednořádkový souhrn toho, co kód dělá.
  • Argumenty: Informace o argumentech, které funkce očekává, včetně jejich datových typů.
  • Návratová hodnota: Informace o návratové hodnotě funkce včetně jejího datového typu.
  • Zvyšuje (volitelné): Informace o jakýchkoli výjimkách, které může funkce vyvolat.

Toto je pouze základní formát, protože existují i ​​​​jiné formáty, které si můžete vybrat jako základ svých dokumentačních řetězců. Nejoblíbenější z nich jsou Epytext, reStructuredText (také známý jako reST), NumPy a Google docstrings. Každý z těchto formátů má svou vlastní syntaxi, jak je znázorněno v následujících příkladech:

Epytext

Dokumentační řetězec ve formátu Epytext:

defnásobit(a, b):

 Vynásobte dvě čísla dohromady.
 @param a: První číslo, které se má vynásobit.
 @type a: int
 @param b: Druhé číslo, které se má vynásobit.
 @typ b: int
 @return: Součin dvou čísel.
 @rtype: int

vrátit se a * b

reStructuredText (reST)

Dokumentační řetězec, který má formát reST:

defnásobit(a, b):

 Vynásobte dvě čísla dohromady.
 :param a: První číslo, které se má vynásobit.
 :type a: int
 :param b: Druhé číslo, které se má vynásobit.
 :typ b: int
 :vrátit se: Součin dvou čísel.
 :rtype: int

vrátit se a * b

NumPy

Dokumentační řetězec, který sleduje formát NumPy:

defnásobit(a, b):

 Vynásobte dvě čísla dohromady.
 Parametry

 a: int
 První číslo, které se má vynásobit.
 b: int
 Druhé číslo k vynásobení.
 Návraty

 int
 Součin dvou čísel.

vrátit se a * b

Google

Dokumentační řetězec ve formátu Google:

defnásobit(a, b):

 Vynásobte dvě čísla dohromady.
 Args:
 a (int): První číslo, které se má vynásobit.
 b (int): Druhé číslo, které se má vynásobit.
 Vrácení:
 int: Součin dvou čísel.

vrátit se a * b

Ačkoli všechny čtyři formáty docstring poskytují užitečnou dokumentaci pro funkci multiply, formáty NumPy a Google jsou snáze čitelné než formáty Epytext a reST.

Jak zahrnout testy do Docstrings

Pomocí modulu doctest můžete do svých docstringů zahrnout testovací příklady. Modul doctest hledá v docstringu text, který vypadá jako interaktivní relace Pythonu, a poté je provede, aby ověřil, že fungují tak, jak mají.

Chcete-li použít doctests, zahrňte do docstringu vzorové vstupy a očekávané výstupy. Níže je uveden příklad, jak byste to udělali:

defnásobit(a, b):

 Vynásobte dvě čísla dohromady.
 Parametry

 a: int
 První číslo, které se má vynásobit.
 b: int
 Druhé číslo k vynásobení.


 Návraty

 int
 Součin dvou čísel.
 Příklady

 >>> násobit(2, 3)
6
 >>> násobit(0, 10)
0
 >>> násobit(-1, 5)
-5

vrátit se a * b

The Příklady sekce obsahuje tři volání funkcí s různými argumenty a pro každé specifikuje očekávaný výstup. Když spustíte modul doctest, jak je uvedeno níže, spustí se příklady a porovná skutečný výstup s očekávaným výstupem.

python -m doctest multiply.py

Pokud existují nějaké rozdíly, modul doctest je hlásí jako selhání. Použití doctests s docstrings, jako je tento, vám pomůže ověřit, že kód funguje podle očekávání. Všimněte si, že doctests nenahrazují komplexnější unit testy a integrační testy pro váš kód Pythonu.

Jak generovat dokumentaci z Docstring

Naučili jste se základy používání docstringů k dokumentaci kódu Pythonu a důležitost vysoce kvalitní dokumentace. Chcete-li to posunout o stupeň výš, možná budete chtít vygenerovat dokumentaci pro své moduly a funkce z jejich příslušných dokumentačních řetězců.

Jedním z nejpopulárnějších generátorů dokumentace, které můžete použít, je Sphinx. Ve výchozím nastavení podporuje formát reST docstring, ale můžete jej nakonfigurovat tak, aby fungoval s formátem Google nebo NumPy.