Use as docstrings para documentar seu código Python

Se você está lendo isso, provavelmente sabe o quanto é importante documentar seu trabalho, desde o início.
Depois de escrito, o código ainda vai ser lido inúmeras vezes.
Programadores experientes conhecem bem a situação de revisitar código escrito meses atrás e — se não estiver bem documentado — ficar coçando a cabeça para entender “o que diabos esta porcaria faz?”
O Python facilita escrever código legível e você só precisa se aproveitar disso.
Um destes recursos são as documentation strings ou texto de documentação — ou docstrings.

Quando posicionada adequadamente, dentro de uma função, a docstring pode informar o que a função faz e como usar corretamente seus parâmetros.
Em editores e IDEs avançadas, o texto da docstring passará a ser exibido a cada vez que a função for invocada dentro do código — como uma ajuda sensível ao contexto.
python docstrings in komodo editor
Na figura, acima, é possível ver o exemplo dentro do Komodo Editor.
Use 3 aspas simples para iniciar uma docstring e, novamente, para finalizar.
Veja um exemplo:

def minha_funcao(parametro=True):
    ''' texto de documentação específico da função minha_funcao
    que leva um único parâmetro, que é verdadeiro por padrão
    '''
    
minha_funcao()

As aspas triplas podem ser usadas aonde você quiser. Serão mais comumente encontradas em docstrings.
Mas você pode usá-las apenas para inserir comentários em múltiplas linhas, em qualquer ponto do seu codigo.

As aspas simples triplas informam ao interpretador Python que se trata de uma string em múltiplas linhas.
Tudo o que você quiser escrever cabe dentro deste espaço — o que inclui, além do texto, as quebras de linha, os espaços em branco ou outras aspas.
Se você for usar docstrings para documentar uma função, tenha em mente que elas devem ser iniciadas logo abaixo da função, como no exemplo dado, logo acima.

Assinar blog por e-mail

Digite seu endereço de e-mail para assinar este blog e receber notificações de novas publicações por e-mail.

Junte-se a 49 outros assinantes

Deixe uma resposta