Como documentar código Python usando Docstrings

Sem a documentação adequada, pode ser difícil entender, manter e depurar seu código. Em Python, você pode usar docstrings para fornecer descrições concisas e exemplos de como o código funciona.

O que são Docstrings?

Docstrings são strings que você pode adicionar ao seu código Python para explicar o que ele faz e como usá-lo. O trecho de código pode ser um Função Python, um módulo ou uma classe.

Docstrings se parecem muito com os comentários padrão do Python, mas têm algumas diferenças. Os comentários do Python fornecem informações adicionais aos desenvolvedores sobre o funcionamento interno do código, como detalhes de implementação ou ressalvas a serem lembradas ao estender o código.

Por outro lado, docstrings fornecem principalmente informações aos usuários do código que podem não necessariamente precisar saber seus detalhes de implementação, mas precisam entender o que ele faz e como usá-lo.

Como Escrever Docstrings

Normalmente, você inclui docstrings no início do bloco de código que deseja documentar. Você deve colocá-los entre aspas triplas (). Você pode escrever docstrings de uma linha ou docstrings de várias linhas.

Docstrings de uma linha são adequadas para código simples que não requer muita documentação.

Abaixo está um exemplo de uma função chamada multiplicação. A docstring explica que a função de multiplicação pega dois números, os multiplica e retorna o resultado.

defmultiplicar(a, b):
Multiplica dois números e retorna o resultado
retornar a * b

Use docstrings de várias linhas para códigos mais complexos que precisam de documentação detalhada.

Considere a seguinte classe Carro:

aulaCarro:

 A aularepresentandoacarroobjeto.
 Atributos:
 quilometragem (float): A quilometragem atual do carro.
 Métodos:
 dirigir (milhas): dirige o carro para o número especificado de milhas.

def__iniciar__(próprio, quilometragem):
 self.mileage = quilometragem
defdirigir(próprio, milhas):

 dirige o carro para o número especificado de milhas.
 Argumentos:
 milhas (float): O número de milhas para dirigir.
 Retorna:
Nenhum

 self.mileage += milhas

A docstring para a classe acima descreve o que a classe representa, seus atributos e seus métodos. Enquanto isso, as docstrings para o método drive fornecem informações sobre o que o método faz, os argumentos que ele espera e o que ele retorna.

Isso torna mais fácil para qualquer pessoa que trabalhe com essa classe entender como usá-la. Os outros benefícios do uso de docstrings incluem:

• Manutenibilidade do código: ao fornecer uma descrição clara de como o código funciona, as docstrings ajudam os desenvolvedores a modificar e atualizar o código sem introduzir erros.
• Colaboração mais fácil: quando vários desenvolvedores estão colaborando na mesma base de código, por exemplo, com o Ferramenta de compartilhamento ao vivo do Visual Studio—docstrings permitem que os desenvolvedores documentem o código de forma consistente para que todos na equipe possam entendê-lo.
• Legibilidade de código aprimorada: Docstrings fornecem um resumo de alto nível do que o código faz, o que permite qualquer pessoa lendo o código para entender rapidamente sua finalidade sem passar por todo o código bloquear.

Formatos de Documentação

Uma boa docstring deve descrever o que um trecho de código faz, os argumentos esperados e detalhes de implementação, se necessário. Ele deve incluir especialmente quaisquer casos extremos dos quais qualquer pessoa que use o código deva estar ciente.

Um formato básico de docstring tem as seguintes seções:

• Linha de resumo: Um resumo de uma linha do que o código faz.
• Argumentos: Informações sobre os argumentos que a função espera, incluindo seus tipos de dados.
• Valor de retorno: Informações sobre o valor de retorno da função, incluindo seu tipo de dados.
• Raises (opcional): Informações sobre quaisquer exceções que a função pode gerar.

Este é apenas um formato básico, pois existem outros formatos que você pode escolher para basear suas docstrings. Os mais populares são Epytext, reStructuredText (também conhecido como reST), NumPy e Google docstrings. Cada um desses formatos possui sua própria sintaxe, conforme mostrado nos exemplos a seguir:

Epytext

Uma docstring que segue o formato Epitext:

defmultiplicar(a, b):

 Multiplique dois números juntos.
 @param a: O primeiro número a ser multiplicado.
 @tipo a: int
 @param b: O segundo número a ser multiplicado.
 @tipo b: int
 @return: O produto dos dois números.
 @rtype: int

retornar a * b

reStructuredText (reST)

Uma docstring que segue o formato reST:

defmultiplicar(a, b):

 Multiplique dois números juntos.
 :param a: O primeiro número a ser multiplicado.
 :digite um: int
 :param b: O segundo número a ser multiplicado.
 :tipo b: int
 :retornar: O produto dos dois números.
 :rtype: int

retornar a * b

NumPy

Uma docstring que segue o formato NumPy:

defmultiplicar(a, b):

 Multiplique dois números juntos.
 Parâmetros

 não
 O primeiro número a ser multiplicado.
 b: inteiro
 O segundo número a ser multiplicado.
 devoluções

 int
 O produto dos dois números.

retornar a * b

Google

Uma docstring que segue o formato do Google:

defmultiplicar(a, b):

 Multiplique dois números juntos.
 Argumentos:
 a (int): O primeiro número a ser multiplicado.
 b (int): O segundo número a ser multiplicado.
 Retorna:
 int: O produto dos dois números.

retornar a * b

Embora todos os quatro formatos docstring forneçam documentação útil para a função de multiplicação, os formatos NumPy e Google são mais fáceis de ler do que os formatos Epytext e reST.

Como incluir testes nas Docstrings

Você pode incluir exemplos de teste em suas docstrings usando o módulo doctest. O módulo doctest pesquisa a docstring em busca de texto que se pareça com sessões interativas do Python e, em seguida, as executa para verificar se funcionam como deveriam.

Para usar doctests, inclua as entradas de amostra e as saídas esperadas na docstring. Abaixo está um exemplo de como você faria isso:

defmultiplicar(a, b):

 Multiplique dois números juntos.
 Parâmetros

 não
 O primeiro número a ser multiplicado.
 b: inteiro
 O segundo número a ser multiplicado.
 devoluções

 int
 O produto dos dois números.
 Exemplos

 >>> multiplicar(2, 3)
6
 >>> multiplicar(0, 10)
0
 >>> multiplicar(-1, 5)
-5

retornar a * b

O Exemplos A seção contém três chamadas de função com argumentos diferentes e especifica a saída esperada para cada uma. Quando você executar o módulo doctest conforme mostrado abaixo, ele executará os exemplos e comparará a saída real com a saída esperada.

python -m doctest multiplicar.py

Se houver alguma diferença, o módulo doctest as relata como falhas. Usar doctests com docstrings como essa ajuda a verificar se o código está funcionando conforme o esperado. Observe que os doctests não são um substituto para testes mais abrangentes testes de unidade e testes de integração para seu código Python.

Como gerar documentação a partir de Docstrings

Você aprendeu o básico do uso de docstrings para documentar seu código Python e a importância de uma documentação de alta qualidade. Para melhorar ainda mais, você pode querer gerar documentação para seus módulos e funções a partir de suas respectivas docstrings.

Um dos geradores de documentação mais populares que você pode usar é o Sphinx. Ele suporta o formato docstring reST por padrão, mas você pode configurá-lo para funcionar com o formato Google ou NumPy.