Python Eficaz

print(repr(palindrome.__doc__))
>>>
'Return True if the given word is a palindrome.'
As docstrings podem ser inseridas em funções, classes e módulos. Essa conexão
é parte do processo de compilar e rodar um programa em Python. A existência
das docstrings e do atributo __doc__ tem três consequências:
• A acessibilidade da documentação facilita o desenvolvimento interativo.
Pode-se inspecionar funções, classes e módulos para ler sua documentação
usando a função nativa help, fazendo com que o interpretador interativo do
Python (conhecido como “shell do Python”) e ferramentas como o IPython
Notebook 1 (http://ipython.org) sejam uma delícia de usar durante o
desenvolvimento de algoritmos, teste de APIs e a criação de pequenos
trechos utilitários de código.
• Ter uma maneira padronizada de definir documentação faz com que seja mais
fácil converter o texto em formatos mais agradáveis visualmente (como o
HTML). Por isso mesmo, surgiram ferramentas de geração de documentação
de excelente qualidade, criadas pela comunidade do Python, como o Sphinx
(http://sphinx-doc.org). Também permitiu que sites financiados pela
comunidade como o Read the Docs (https://readthedocs.org), que oferece
hospedagem gratuita para documentação lindamente formatada de projetos
de código aberto do Python.
• A documentação acessível, de primeira classe e luxuosamente apresentada do
Python encoraja as pessoas a escrever mais documentação. Os membros da
comunidade do Python têm fé inabalável na importância da documentação.
Consideram que código bom é código bem documentado. Isso significa que a
maioria das bibliotecas open source do Python têm documentação decente.
Para participar desse verdadeiro movimento em prol da boa documentação, é
necessário obedecer a algumas regrinhas quando for escrever docstrings. Os
detalhes e orientações a respeito da boa redação de docstrings estão descritas na
PEP 257 (http://www.python.org/dev/peps/pep-0257/), mas há algumas boas
práticas que devemos sempre seguir.
Documentando módulos
Todo módulo deve, sem exceção, ter uma docstring no nível mais alto. Esse
www.full-ebook.com