Documentar funções com docstrings e tipos simples

Uma docstring é uma string literal colocada como a primeira instrução do corpo da função. Ela fica indentada e pode usar aspas triplas duplas (""") ou simples (''').

As aspas triplas permitem escrever uma ou várias linhas. No resumo inicial, diga o que a função faz — não narre cada linha da implementação.

A string aparece imediatamente depois da assinatura e tem a mesma indentação das demais instruções do corpo.

Um comentário iniciado por # pode explicar o código, mas não é uma docstring. Da mesma forma, uma string colocada depois de outra instrução não é a docstring da função.

Portanto, confira dois pontos: é uma string literal e é a primeira instrução do corpo.

Somente caso_correto contém uma docstring reconhecida como documentação da função.

Comece a docstring com um resumo direto da finalidade da função. Depois de uma linha em branco, registre somente os detalhes necessários para usá-la corretamente:

• Parâmetros: o significado de cada entrada, incluindo unidades e valores padrão relevantes.
• Retorno: o que o resultado representa, e não apenas que ele é um número ou texto.
• Condição de uso: o que deve ser verdadeiro para a chamada fazer sentido.
• Exemplo: uma chamada breve e seu resultado esperado.

Esses rótulos em português formam uma organização simples; você não precisa adotar um padrão externo.

A docstring pode ser lida como um conjunto de blocos, começando por uma visão geral e avançando para os detalhes de uso.

A documentação explica as unidades, o valor padrão, a condição esperada e o significado do resultado.

Considere que dias representa a quantidade de dias do período e que total_litros representa o consumo total em litros.

Uma função pode alterar um argumento e, ao mesmo tempo, não retornar um valor útil. Nesse caso, a docstring deve registrar as duas informações separadamente: o efeito sobre o argumento e o retorno None.

A própria lista recebida ganha um novo elemento. A função não cria nem retorna outra lista.

Uma anotação registra o tipo esperado logo na assinatura da função:

• No parâmetro, use nome: tipo.
• No retorno, use -> tipo antes dos dois-pontos que iniciam o corpo.
• Se houver valor padrão, a anotação vem antes dele: ativo: bool = True.

As anotações descrevem os tipos esperados. A docstring continua responsável por explicar o significado dos dados, as condições de uso e os efeitos da função.

Observe a posição de cada elemento na assinatura anotada.

Use int, float, str e bool para registrar expectativas simples. A anotação não substitui a docstring: saber que percentual é um float, por exemplo, não explica que ele representa uma porcentagem.

As implementações continuam iguais; somente as assinaturas receberam anotações.

Quando uma função não retorna um valor com return, anote o retorno como -> None. Isso também vale quando a função produz um efeito, como alterar a própria lista recebida.

Neste exemplo, o parâmetro da coleção permanece sem anotação. A docstring informa que ele é uma lista e registra o efeito relevante.

As anotações informam quais tipos são esperados, mas o Python não converte nem rejeita automaticamente um argumento durante a chamada. Se o corpo apenas devolve o argumento, o mesmo valor sai da função.

Apesar das anotações com int, a chamada recebe e devolve um texto.

Uma operação do corpo pode não funcionar com certo valor. Isso não significa que a anotação verificou o tipo: foi a própria operação que encontrou um valor inadequado.

A docstring informa que quantidade deve ser positiva, mas não implementa essa verificação.

help apresenta informações sobre uma função sem chamá-la. Passe o nome da função, sem parênteses: help(aplicar_desconto). Se você escrever help(aplicar_desconto(...)), a chamada será executada primeiro e help receberá o resultado, não a função.

Execute esta definição no Python do seu computador. Depois, consulte a função com a última linha.

Na saída, localize a assinatura com nomes, anotações e valor padrão. Logo abaixo aparece a docstring, com finalidade, parâmetros, retorno, condições e exemplo. A apresentação exata pode variar conforme o ambiente.

O cabeçalho pode mudar, mas estas são as informações principais que você deve reconhecer.

Agora faça uma chamada manual e compare o resultado observado com o exemplo e o significado de desconto descritos na docstring.

Execute após definir a função.

Copie o código abaixo para um arquivo no seu computador. Complete apenas as assinaturas e as docstrings.

Na primeira função, anote os dois parâmetros e o retorno. Documente a condição de que quantidade deve ser positiva.

Na segunda, mantenha itens sem anotação, anote texto com str e use -> None. Deixe explícito que a própria lista recebida é alterada e que a função retorna None.

Substitua cada comentário pela documentação ou anotação solicitada, sem alterar as instruções do corpo.

Execute o arquivo e examine a saída de help. A apresentação pode variar entre ambientes, mas deve mostrar as assinaturas anotadas e as docstrings.

Depois, confira as chamadas: os cálculos devem produzir 15.0 e 20.0; a lista deve se tornar ['Ana', 'Bia']; e resultado deve ser None.

Revise se os nomes, valores padrão e tipos da assinatura coincidem com a docstring. Verifique também se a precondição, o retorno e o efeito sobre a lista correspondem ao comportamento observado.

Use o esquema como um ciclo de conferência: leia a assinatura, compare com a docstring e observe o resultado das chamadas.