Como Documentar Código em Python – Um guia pelo Docstring

Neste artigo nós vamos fazer um tour completo pelo docstring, que está documentada na PEP 257. É de extrema importância que você saiba como documentar código em Python, ou em qualquer outra linguagem.

Documentar o código, ou seja, escrever comentários ao longo das suas classes, métodos, etc. pode não ser uma tarefa tão popular entre diversas linguagens.

Há inclusive quem diga que você só precisa documentar o seu código caso ele esteja mal escrito.

Bem, este artigo é para falar sobre isso, sobre os motivos para se realizar uma documentação bem feita, como utilizar corretamente o docstring do Python, etc.

Porque Documentar o Código é Importante?

code quality meme




Bem, talvez essa seja uma pergunta um pouco óbvia, e todas as possíveis respostas mais óbvias ainda. Porém, eu não vou passar por este artigo sem dar alguns exemplos do porque documentar código é importante.

Bem, primeiramente este artigo fala sobre docstrings e Python. Então vamos começar falando sobre o Zen of Python.

Explicit is better than implicit.

Lembram-se? Explícito é melhor que implícito. Quer algo mais direto do que escrever o que exatamente o seu código está fazendo?

Readability counts.




Mais uma da PEP20! Leitura conta!

E novamente, quer algo mais legível do que a sua própria explicação do que exatamente o seu código está fazendo?

E essas afirmações não servem apenas para documentar código em Python, servem para todas as linguagens!

It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.

Fonte: What nobody tells you about documentation




Ou em uma tradução livre: “Não importa o quão bom o seu software é, porque se a documentação não for boa o suficiente, ninguém irá usá-lo“.

Nós Escrevemos Código Para os Outros

A verdade é que nós escrevemos código para os outros.

Em primeiro lugar, nosso código deve traduzir um desejo dos usuários que consumirão o que nós estamos construindo.

Porém, tão importante quanto os usuários que consumirão nosso produto, são os outros desenvolvedores que darão manutenção em nosso código.

Se muitas vezes, nós mesmos não entendemos direito o nosso próprio código, imagina os outros?

Eu tenho uma regra pessoal para considerar um código bom ou ruim.

Se eu abro um arquivo e não consigo entender rapidamente qual a ideia geral daquele código, para mim, ele é ruim.

Não importa se é o algorítimo mais otimizado, se você criou a arquitetura perfeita (na sua cabeça) e fica olhando como está simples e bonito.

Porém, se o seu time abre aquele código, e tem que ficar lendo linha por linha do código para tentar entender o que diabos está acontecendo ali, sinto muito, mas eu considero isso um código ruim.

Mas o código nem sempre é fácil de ler mesmo, muitas vezes são operações complexas e talvez confusas que estamos realizando.

Por isso documentar o código faz parte da arte de escrever código de qualidade.

Como Documentar Código em Python?

Mas então fica a pergunta, como documentar o nosso código quando estamos escrevendo nossos programas em Python?

Code Tells You How, Comments Tell You Why - jeff atwood

Via Coding Horror (aka Jeff Atwood)

Eu comecei recentemente a escrever uma biblioteca em Python chamada SEO.

E como eu estou falando neste artigo, documentar o código é de extrema importância, ainda mais quando estamos escrevendo uma biblioteca pública hospedada no Python Package Index.

pypi logo

Então neste artigo, eu vou começar documentar o início deste projeto enquanto eu escrevo este artigo.

Mas para falar bem a verdade, existem diversas maneiras de se documentar o código.

Em cada linguagem existem padrões particulares e ferramentas que são utilizadas para este fim.

Em Python, para escrevermos um comentário, basta utilizarmos o caracter #.

Então vamos lá, na biblioteca SEO, eu escrevi uma função chamada get_fake_headers, onde eu retorno algumas informações “falsas” para realizar um request simulando um browser real.


Que tal escrevermos o nosso primeiro comentário?!

Como Documentar Código em Python com Docstrings

Acima nós apenas iniciamos a nossa jornada na documentação, realizando um comentário sobre a variável useragent, e o porque ela existe.

Não há nada de errado nisso, mas vamos seguir e ver como documentar uma função com docstrings.

Para documentar o nosso código utilizando docstrings, nós adicionamos um comentário logo abaixo da declaração da função, entre “””.


Olha que legal agora, se utilizarmos a função help:


Nós teremos o resultado:

Padrões no Docstring

code quality cost

Bem, infelizmente, nós não temos aqui uma regra oficial para nos guiar.

Porém, existem alguns guias muito bons para estruturar os nossos comentários. O meu preferido é a padronização realizada pelo Google.

Na minha opinião, ela é a mais fácil de escrever e principalmente, de ler. Porém existem outras duas muito populares também, que são a do NumPy, e o reStructured Text.

Padronizações:

  1. Google
  2. reStructured Text
  3. NumPy

Aqui realmente não há campeões. A melhor opção é aquela que você e a sua equipe preferem, e o mais importante, a que vocês mantenham o padrão.

Como eu disse anteriormente, a minha favorita é a do Google, então neste artigo, nós continuaremos com os padrões dele.

Docstrings em Funções

Para as padronizações do Google, toda função deve necessariamente possuir o seu docstring, a não ser que todos os casos a seguir se faça presente:

  • Não é visível externamente
  • Muito pequena
  • Óbvia

É importante ressaltar aqui que a docstring deve descrever o que a função faz, e não como ela é implementada. Informações sobre códigos complexos, etc. devem ser inseridas na forma de comentário junto com o código.

Outro ponto importante aqui é que, determinados aspectos da função devem ser documentados em seus respectivos blocos específicos.

Args

Contém a lista de todos os parâmetros pelo nome.

Caso o código não utilize tipificação, o tipo da variável deve ser fornecida.

E claro, a parte mais importante, uma descrição da variável deve ser fornecida.

Returns

Esta é uma sessão que é obrigatória apenas em casos que a função retorne efetivamente algum valor. Caso o valor do retorno seja None, ela não é obrigatória.

Ela também não se torna obrigatória em caso do início da docstring já informar o que será retornado, como por exemplo: “”” Retorna uma lista de usuários ativos.”””

Raises

Deve conter a lista de todas as exceptions relevantes para a interface.

Documentar Código em Python: Exemplos

Aqui seguem alguns exemplos de como documentar código em Python utlizando docstrings em funções e métodos.


Segue um exemplo em que não especificamos uma seção de retorno, pois ele já informado no início do docstring.

Nós também não especificamos o tipo do argumento informado, pois tipificamos tanto o parâmetro quanto o retorno da função:

Docstrings em Classes

Nós vimos como documentar uma função e/ou método, porém documentar classes também é de extrema importância.

flask docstring

Exemplo de docstring do Flask

Aqui não há muita novidade. Toda classe deve possuir um docstring logo abaixo a sua definição.

Caso ela possua atributos públicos, eles devem ser descritos dentro de uma seção Attibutes, no mesmo formato utilizado nos métodos e funções.

Conclusão

Documentar código em Python é uma tarefa muito importante.

E novamente, documentar código, garantir que o seu código seja de fácil entendimento e leitura é uma tarefa a ser realizada em qualquer linguagem.

Então lembrem-se sempre, o código mostra como, mas a documentação mostra o porque aquilo está sendo feito!

Se ficou alguma dúvida, sugestão, etc., não deixe de comentar abaixo!

E documentem o seu código!

Links Importantes e Referências




Leave a Reply