Za několik let, co se živím programováním v pythonu, jsem na narazil na různé guideliny jak psát a na jedněch sem se i podílel. Tématem, které mi vždy přišlo takové důležitě-nedůležité je, jak psát docstringy, resp. dokumentaci kódu.
To se netýká týmů, které používají automatickou generaci dokumentace jako je třeba Sphinx, pydoctor, Doxygene a další., protože pro funkci těchto generátorů je zapotřebí mít konzistentní dokumentaci a tedy dbát na to při review (a samozřejmě znát možnosti daného generátoru).
Na velkých projektech, které nemají dobře definované coding-guidelines, tedy nemají ani definované jak mají vypadat docstringy, to může vypadat i tak, že v jednom modulu, nalezenete v rámci jedné třídy několik různých zápisů docstringu.
Pokud to není definováno v rámci projektu, tak by měli být docstringy konzistentní alespoň v rámci modulů, případně podprojektů. Vzhledem k tomu, že často pak člověk narazí i na zvláštní mix, kdy kodér chtěl napsat docstring v nějakém stylu, ale nevěděl jak je ten správný, tak z toho nakonec vyšl jakýsi šlechtěnec dvou typů, případně s novými standardy.
Docstring je víceřádkový string, které jsou uvozené a zakončené třemi dvojitýma uvozovkama:
"""
Tohle je docstirng
"""Docstring můžete najít na několika místech:
Základy ohledně docstringů jsou definovány v PEP-257.
Mezi nejčsatěji používané docstringy patří:
Epytext je založený na docstringu