Python Eficaz

yield) quando for iterado.
• Se a função for uma corrotina (consulte o Item 40: “Considere usar corrotinas
para rodar muitas funções simultaneamente”), a docstring deve conter o que a
corrotina produz (com yield), o que se espera receber das expressões yield e
quando a iteração será encerrada.
Nota
Depois de escrever as docstrings para seus módulos, é importante manter a
documentação atualizada. O módulo nativo doctest torna fácil testar os
exemplos de uso descritos nas docstrings para garantir que o código-fonte e
sua documentação não divirjam com o passar do tempo.
Lembre-se
• Escreva documentação para todo e qualquer módulo, classe e função usando
docstrings. Mantenha a documentação atualizada à medida que o código
evolui.
• Para módulos: apresente o conteúdo do módulo e inclua quaisquer classes e
funções importantes que os usuários do módulo precisam, necessariamente,
conhecer e entender.
• Para classes: documente o comportamento, atributos importantes e
comportamento de subclasses na docstring logo na linha imediatamente
seguinte ao comando class.
• Para funções e métodos: documente cada argumento, valor de retorno,
exceções geradas e outros comportamentos na docstring logo após o
comando def.
Item 50: Use pacotes para organizar módulos e criar
APIs estáveis
À medida que o tamanho do programa (e de seu código-fonte) cresce, é natural
que queiramos reorganizar a sua estrutura interna. Dividimos funções
complicadas em várias funções mais simples, refatoramos as estruturas de dados
em classes auxiliares (consulte o Item 22: “Prefira classes auxiliares em vez de
administrar registros complexos com dicionários e tuplas”) e segregamos cada
funcionalidade em um módulo em separado, criando dependências entre eles
www.full-ebook.com