4 padrões de docstring em Python

Uma docstring é uma string literal presente na primeira linha da definição de um módulo, classe ou função. O docstring de qualquer objeto pode ser acessado através de um atributo especial chamado __doc__.

Existem diferentes padrões de docstring, sendo oficialmente recomendado pela PEP 287 o padrão reStructuredText (reST). Segue os padrões que podem ser adotados em um projeto:

reStructuredText

O padrão reStructuredText (reST) é o mais prevalente, sendo principalmente usado pelo Sphinx e padrão no JetBrains PyCharm.

Exemplo:

Google

O padrão da empresa Google é especificado em seu guia de estilo. Ele é uma alternativa ao padrão reST no Sphinx.

Exemplo:

EpyText

O padrão EpyText é baseado no javadoc, que é um padrão historicamente prevalecido. Ele foi a base para o Epydoc, que é uma alternativa ao Sphinx.

Exemplo:

Numpydoc

O padrão Numpydoc foi baseado no guia de estilo do Google mas com suas modificações para o projeto NumPy/SciPy. Ele pode ser usado no Sphinx.

Exemplo:

Conclusão

Os programadores são naturalmente uma raça preguiçosa e isso é muito bom. Nós reutilizamos funções, classes, módulos e pacotes. Através de docstrings, Python nos permite documentar o código de forma clara e de fácil manutenção.

Like what you read? Give Patrick Porto a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.