Documentar um código é uma das práticas mais importantes na programação. No Python, isso pode ser feito de forma simples e elegante com docstrings. Elas ajudam outros desenvolvedores (e você mesmo no futuro) a entenderem o que cada parte do programa faz. Neste artigo, você vai aprender o que são docstrings, como usá-las corretamente e boas práticas para criar uma documentação clara e útil.
O que são docstrings no Python
As docstrings são strings de documentação. Elas servem para descrever o que um módulo, função, classe ou método faz.
A principal diferença em relação a um simples comentário é que as docstrings ficam acessíveis dentro do próprio código, podendo ser visualizadas com ferramentas ou pela função help().
Um exemplo simples:
def somar(a, b):
"""Retorna a soma de dois números."""
return a + bSe você executar help(somar), o Python exibirá o texto da docstring, mostrando exatamente o que a função faz.
Por que documentar com docstrings é importante
Documentar o código não é apenas uma boa prática, é um investimento. Algumas razões importantes para usar docstrings:
- Facilita a leitura: o próximo programador (ou você no futuro) entenderá rapidamente o propósito da função.
- Ajuda em ferramentas automáticas: frameworks como Sphinx e pdoc podem gerar documentação completa a partir das docstrings.
- Melhora a colaboração: em projetos com várias pessoas, todos seguem o mesmo padrão.
- Integração com IDEs: editores como PyCharm e VSCode exibem as docstrings quando você passa o mouse sobre funções e classes.
Onde usar docstrings
Você pode adicionar docstrings em praticamente qualquer estrutura de código:
- Módulos: descrevem o propósito do arquivo Python.
- Funções e métodos: explicam o que a função faz e o que cada parâmetro representa.
- Classes: descrevem o objetivo da classe e como ela deve ser usada.
- Pacotes: podem incluir docstrings no arquivo
__init__.pypara explicar o conjunto de módulos.
Exemplo com cada tipo:
"""Módulo de operações matemáticas básicas."""
class Calculadora:
"""Classe que realiza operações de soma e subtração."""
def somar(self, a, b):
"""Retorna a soma de dois números."""
return a + b
def subtrair(self, a, b):
"""Retorna a subtração de dois números."""
return a - bComo escrever uma boa docstring
Uma boa docstring deve explicar claramente o propósito da função ou classe, e não repetir o óbvio.
Veja algumas dicas práticas:
1. Use frases curtas e diretas
A primeira linha deve ser uma descrição simples do que o código faz.
def dividir(a, b):
"""Divide dois números e retorna o resultado."""2. Adicione detalhes extras quando necessário
Use uma linha em branco após a descrição inicial, e em seguida explique mais detalhes ou parâmetros.
def dividir(a, b):
"""
Divide dois números e retorna o resultado.
Parâmetros:
a (float): primeiro número
b (float): segundo número
Retorna:
float: resultado da divisão
"""3. Siga um padrão de formatação
Existem diferentes estilos, como Google, NumPy e reStructuredText (reST).
Escolher um padrão é importante, especialmente em equipes.
Exemplo no estilo Google:
def multiplicar(a, b):
"""Multiplica dois números.
Args:
a (float): primeiro número
b (float): segundo número
Returns:
float: resultado da multiplicação
"""Principais padrões de docstring
Abaixo, uma comparação entre três estilos populares:
| Estilo | Características principais | Ideal para |
|---|---|---|
| Simples e fácil de ler, usa “Args” e “Returns”. | Pequenos e médios projetos. | |
| NumPy | Mais detalhado, usado em projetos científicos. | Projetos com fórmulas e arrays. |
| reST | Compatível com o Sphinx e ideal para documentação automática. | Grandes bibliotecas e APIs. |
Boas práticas ao criar docstrings
- Evite repetições. Se a função se chama
somar, não diga “Função que soma números”. Prefira “Retorna a soma de dois valores”. - Mantenha o tempo verbal no presente: “Retorna” em vez de “Retornará”.
- Não comente o óbvio.
- Use exemplos curtos, mas claros.
- Siga o mesmo idioma em todo o projeto (seja português ou inglês).
- Atualize sempre: se mudar a função, atualize a docstring também.
- Padronize: use o mesmo estilo em todo o código.
Docstrings em classes e métodos
Em classes, a docstring deve explicar o que a classe representa e como deve ser usada.
Nos métodos, documente apenas o que não for óbvio.
class ContaBancaria:
"""Representa uma conta bancária simples."""
def __init__(self, titular, saldo=0):
"""
Inicializa uma nova conta.
Args:
titular (str): nome do titular.
saldo (float, opcional): valor inicial. Padrão é 0.
"""
self.titular = titular
self.saldo = saldo
def depositar(self, valor):
"""Adiciona um valor ao saldo da conta."""
self.saldo += valorComo visualizar docstrings no Python
Você pode visualizar a docstring de qualquer função ou classe com o comando help():
help(ContaBancaria)Isso mostrará todo o texto da docstring diretamente no terminal.
Também é possível acessar a docstring diretamente com o atributo __doc__:
print(ContaBancaria.__doc__)Gerando documentação automática
Ferramentas como Sphinx, pdoc, Doxygen e MkDocs permitem transformar suas docstrings em documentação completa com páginas HTML.
Essas ferramentas leem as docstrings diretamente do código e geram sites de documentação prontos para publicar.
Se você mantém um projeto open source no GitHub, usar uma dessas ferramentas é uma excelente forma de mostrar profissionalismo e organização.
Erros comuns ao usar docstrings
- Esquecer de adicionar a docstring em funções novas.
- Usar comentários no lugar errado (fora das aspas triplas).
- Escrever docstrings muito genéricas, como “Função principal”.
- Não manter o padrão entre os arquivos.
- Deixar docstrings desatualizadas após alterar o código.
Conclusão
As docstrings são uma das formas mais eficientes de documentar código Python. Elas tornam seu projeto mais organizado, colaborativo e profissional.
Ao adotar um estilo padronizado e manter as docstrings sempre atualizadas, você facilita a vida de quem lê e usa o seu código.
Com boas docstrings, o seu código fala por si mesmo.
Perguntas Frequentes (FAQ)
1. O que é uma docstring?
É uma string usada para documentar o que uma função, classe ou módulo faz.
2. Qual a diferença entre comentário e docstring?
Comentários não aparecem na ajuda do Python, docstrings sim.
3. Onde colocar a docstring?
Logo abaixo da definição da função, classe ou módulo.
4. Que aspas devo usar na docstring?
Use aspas triplas """ no início e no fim do texto.
5. Posso usar docstring em português?
Sim, o importante é manter o mesmo idioma em todo o projeto.
6. O que significa o padrão Google em docstrings?
É um formato simples que organiza os parâmetros e retornos com “Args” e “Returns”.
7. Como vejo a docstring de uma função?
Use o comando help(nome_da_função) no terminal.
8. Ferramentas como Sphinx leem docstrings?
Sim, elas geram documentação automaticamente a partir delas.
9. É obrigatório usar docstrings no Python?
Não, mas é fortemente recomendado.
10. Quantas linhas deve ter uma docstring?
O suficiente para explicar o que faz, sem exageros.
11. Posso usar exemplos dentro da docstring?
Sim, exemplos ajudam a entender o uso da função.
12. Preciso atualizar docstrings quando mudo o código?
Sim, sempre atualize para evitar inconsistências.
