Python Eficaz

literal em formato string é sempre a primeira declaração em um arquivo-fonte.
As docstrings devem usar três aspas duplas ("""). O objetivo dessa primeira
docstring é apresentar o módulo, dizer o que ele faz e o que contém.
A primeira linha da docstring deve ser uma única sentença descrevendo a
finalidade do módulo. Os parágrafos seguintes devem conter os detalhes que
todos os usuários desse módulo precisam saber para bem usá-lo. A docstring do
módulo também serve como ponto de partida, no qual podemos destacar as
classes e funções mais importantes.
O exemplo a seguir mostra uma típica docstring de módulo:
# words.py
#!/usr/bin/env python3
"""Library for testing words for various linguistic patterns.
Testing how words relate to each other can be tricky sometimes!
This module provides easy ways to determine when words you've
found have special properties.
Available functions:
- palindrome: Determine if a word is a palindrome.
- check_anagram: Determine if two words are anagrams.
...
"""
# ...
Se o módulo for uma ferramenta que pode ser usada na linha de comando, sua
docstring também é um ótimo lugar para colocar as instruções de uso.
Documentando classes
Toda classe deve ter uma docstring principal, logo no início da classe, que segue
em grande parte os mesmos moldes da docstring geral do módulo. A primeira
linha traz uma única sentença que descreve a finalidade da classe. Os parágrafos
seguintes discutem os detalhes importantes de como a classe funciona.
Os métodos e atributos públicos importantes devem ser destacados na docstring
www.full-ebook.com