Docstring, anotace a coding style

Docstring
Anotace
Coding style

Docstring

Docstring je jeden z dobrých způsobů, jak získat informace o funkcích a třídách, a také udržet program čitelný.
Docstring (documentation string), neboli dokumentační řetězec, je textový řetězec, který se uvádí za příkazem def (při definici funkce).

Kvůli čitelnosti ve zdrojovém kódu se uvozuje třemi uvozovkami, což také umožňuje snadno rozepsat dokumentaci k funkci na více řádek (není to však nutné).

Docstring zůstává i ve zkompilovaném pythonovském modulu (pokud při kompilaci nebo po ní záměrně nepožádáte o jejich zrušení). O modulech v Pythonu bude řeč v některé z dalších kapitol.

Jelikož i funkce je objektem, má také své atributy (o objektech bude také řeč později). Pokud napíšete při definici funkce docstring, najdete jej v atributu funkce __doc__.

def funkce():
"""Tato funkce nedela nic.

Je tu jen na ukazku docstringu.
Vrací hodnotu None, protože nemá v těle uveden příkaz return."""
pass

Při psaní docstringu je dobrým zvykem napsat na první řádku krátkou větu, která vystihuje to, co funkce dělá, pak prázdnou řádku a pak podrobnější popis funkce (předpoklady úspěšného použití, mezní podmínky atd.).
Nemusím asi dodávat, že by měla být dokumentace psána v angličtině (nebo alespoň bez diakritiky, pokud je sebemenší šance, že se zdrojákem bude zaobírat někdo ze zahraničí).

>>> funkce() # funkce nic nedělá, jen vrací None
>>> funkce.__doc__
'Tato funkce nedela nic.\n\n Je tu jen na ukazku docstringu.\n Vrací hodnotu None, protože nemá v těle uveden příkaz return.'
>>> print(funkce.__doc__)
Tato funkce nedela nic.

Je tu jen na ukazku docstringu.
Vrací hodnotu None, protože nemá v těle uveden příkaz return.

Docstring využívá i funkce help(). Zkuste si pustit help(funkce). Docstring také využívají různé programy na automatické generování dokumentace kódu.

Prohlédněte si docstringy standardních metod Pythonu. Například funkce min() zobrazuje na prvních dvou řádkách příklad použití a dále pak popisuje co funkce dělá.

>>> print(min.__doc__)
min(iterable[, key=func]) -> value
min(a, b, c, ...[, key=func]) -> value

With a single iterable argument, return its smallest item.
With two or more arguments, return the smallest argument.

V dokumentaci Pythonu (na webu) naleznete většinou podrobnější informace o standardních funkcích a objektech Pythonu, než v jejich docstringu.

Dalším zdrojem informací může být atribut __dict__ (probereme později, týká se modulů), nebo funkce dir() (probrali jsme dříve).

O objektech, atributech a metodách se pojednává v další kapitole – Třídy a objěkty. Tak ještě jednu kapitolu vydržte a bude vám hned jasnější názvosloví zde používané.

Anotace

Anotace jsou součástí Pythonu od verze 3.0.

Anotace je další způsob, jak okomentovat kód. Python anotace k ničemu nepoužívá (ignoruje je). Je tak úplně jedno, jestli je použijete nebo ne, mají čistě dokumentační hodnotu.

Anotacemi můžete říci, jaké typy očekáváte u argumentů funkce a (nebo) jaký typ funkce vrací jako svou návratovou hodnotu.

Anotace jsou dostupné v atributu __annotations__, což je slovník, jehož klíči jsou názvy anotovaných argumentů, nebo return pro popis návratové hodnoty.

Příklad jsem převzal z tutoriálu k anotacím.

>>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here":
... print("Annotations:", f.__annotations__)
... print("Arguments:", ham, eggs)
...
>>> f('wonderful')
Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
Arguments: wonderful spam
>>> f() # ham nemá implicitní hodnotu 42!
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: f() missing 1 required positional argument: 'ham'

Nápověda k návratové hodnotě se píše mezi -> a : na prvním řádku definice funkce. Nápověda k argumentům se píše za název argumentu a dvojtečku (následovat může implicitní argument funkce).

Taky si všimněte, že do nápovědy nemusíte dávat jen text, ale můžete tam dát jakýkoliv výraz. Třeba, jako v příkladu, třídu int, nebo číslo 42.
Následující příklad je hloupý, ale demnostruje tuto vlastnost.

>>> def f(arg: max(3, 5)):
... pass
...
>>> print(f.__annotations__)
{'arg': 5}

Coding style

Coding style je takové nepsané pravidlo, jak byste měli formátovat zdrojové kódy, které je pro Python popsané v PEP 8.

PEP (Python Enhancement Proposals) jsou dokumenty, které popisují návrhy na vylepšení jazyka Python. S tím si teď nelamte hlavu :-).

Smyslem tohoto coding style je, aby se váš kód lépe četl. A to nejen vám, ale hlavně ostatním programátorům (prostě aby zdrojáky nebyli každá ves jinej pes).

Stručný výtah z Coding style

Používejte k odsazení 4 mezery, ne tabulátory.
Tabulátory jsou většinou zdrojem zmatení v odsazování a je lepší se jim vyhnout. Tohle je zrovna něco, čím se nedržím a odsazuji tabulátory :-)
Zalamujte řádky tak, aby nebyli delší než 79 znaků.
To pomáhá uživatelům s malými displeji (Linuxová konzole měla tradičně na šířku 80 znaků) a naopak na velkých displejích umožňuje mít otevřené více zdrojáků vedle sebe.
Používejte prázdné řádky k oddělení funkcí a tříd a velkých bloků kódu od kódu uvnitř funkcí.
Když je to možné, dávejte komentáře na vlastní řádky (né jak to dělám často v příkladech vedle volání funkce atp.).
Používejte docstringy (a anotace).
Používejte mezery kolem operátorů a za čárkami:
a = f(1, 2) + g(3, 4)
Pojmenovávejte třídy a funkce konzistentně.
Konvence je používat Velbloudí notaci (CamelCase) pro jména tříd a malá_písmena_s_podtržítky pro jména funkcí a metod.
Vždy používejte self jako jméno pro první argument metody (použití self v metodách proberu v kapitole o třídách a objektech).
Nepoužívejte ve zdrojácích jiné kódování než UTF-8. Nejlepší bude, když si vystačíte s obyčejnými ASCII znaky (anglická abeceda).
Nepoužívejte v názvech funkcí a tříd non-ASCI znaky.