Docstrings final

Criando documentação para suas funções!

Voltemos ao último exemplo da aula anterior (Funções), que era uma função para calcular o quadrado de um número:

def quadrado(x):
  return x * x

Você pode tentar usar o comando help() para ver o que acontece:

help(quadrado)

O resultado será algo assim:

Help on function quadrado in module __main__:

quadrado(x)

Não é muito útil, concorda? Mas o que você esperava? O python só sabe executar a sua função, ele não sabe para que ela serve!

Se você quiser fornecer mensagens para o comando help(), coloque uma docstring na sua função. Uma docstring é quanquer mensagem de texto delimitada por pares de três aspas simples (''') ou duplas (""") logo após o comando def, como no exemplo abaixo:

def quadrado(x):
  '''
    uma função para calcular 
    o quadrado de um número
    
    Entrada (input): x, um float ou int
    Saída (output): o quadrado de x 
  '''
  return x * x

Se você agora usar o comando help(quadrado), verá a mensagem acima! Claro que a função acima é muito fácil, mas funções podem ter vários argumentos, alguns opcionais, é também vários valores retornados. É sempre bom, portanto, acrescentar uma docstring para auxiliar os usuários a usar corretamente as funções que você cria.

Obviamente eu espero que o seu projeto de software faça amplo uso de docstrings, além de comentários usuais ao longo do código!

Teste seu código:

Página atualizada em 07/06/20