Comentários em Python: linha única, múltiplas linhas e docstrings

Comentários são para humanos

O Python ignora comentários. Esse é o truque inteiro. Tudo que você marca como comentário fica invisível para o interpretador — está ali puramente para a pessoa lendo seu código, que geralmente é você daqui a seis meses, se perguntando o que você do passado estava pensando.

Dito isso, um comentário que só repete o que o código obviamente faz não vale a pena. Os melhores comentários explicam por que — uma restrição, um contorno, uma decisão que não é óbvia pelo código em si. O código já te diz o que está acontecendo.

Comentários de linha única com #

A forma básica é um # seguido da sua nota:

Você também pode encaixar um comentário curto no fim de uma linha. Por convenção, deixe pelo menos dois espaços antes do #:

O Python lê # em qualquer lugar fora de uma string e trata o resto da linha como comentário. Essa parte de "fora de uma string" importa: # dentro de aspas é só um caractere.

O #section-2 dentro da string é parte da URL. O Python só entra em modo "comentário" quando encontra o # depois da string fechar.

Comentando várias linhas

O Python não tem comentário de bloco /* */. Para pular várias linhas, coloque # no começo de cada uma:

Você quase nunca digita esses #s na mão. Todo editor decente tem um atalho "toggle line comment" que adiciona ou remove # em todas as linhas selecionadas:

• VS Code: Cmd + / (macOS) ou Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / ou Ctrl + /
• Vim: depende dos seus plugins; vim-commentary amarra gcc para uma linha e gc para uma seleção.

Aprenda o atalho do seu editor uma vez, e "comentar esse bloco para testar uma coisa" vira operação de uma tecla.

O truque das aspas triplas (e por que não é comentário de verdade)

Você às vezes vai ver código assim:

Tecnicamente isso é uma expressão de string que é descartada. O Python lê, avalia e joga o resultado fora. Se comporta como comentário, mas não é um. Estilisticamente, isso só é uma boa ideia num lugar específico: como docstring.

Docstrings: o único lugar onde aspas triplas pertencem

Uma docstring é uma string com aspas triplas colocada como primeira instrução de uma função, classe ou módulo. O Python reconhece como documentação e deixa disponível em tempo de execução via a função help() e o atributo __doc__:

Duas coisas tornam docstrings agradáveis:

1. Ferramentas como IDEs, help() e geradores de documentação leem automaticamente. Um comentário em cima da função não ganha nada do tipo.
2. Elas descrevem a função no ponto de chamada — quando alguém passa o mouse sobre discount(...) no editor, a docstring aparece como dica.

Existe uma convenção (PEP 257) para o que vai na docstring: um resumo de uma linha na primeira linha, uma linha em branco e depois uma descrição mais longa se necessário. Não se estresse com o formato exato no primeiro dia — uma linha simples já é muito melhor do que nenhuma docstring.

O que comentários bons realmente dizem

Algumas diretrizes que poupam muito sofrimento futuro:

• Prefira descrever por que em vez de o quê. # Loop over the users é ruído; # Retry on 503 — Redis sometimes dies mid-deploy é ouro.
• Atualize comentários quando mudar o código. Um comentário errado é pior do que nenhum comentário. Comentários desatualizados enganam ativamente leitores futuros.
• Não comente código e deixe lá. Se não precisa, apague. O controle de versão lembra. Um arquivo salpicado de blocos comentados vira pouco confiável rápido.
• Pule o óbvio. x = x + 1 # increment x não adiciona nada.

Em resumo

Comentários são grátis para escrever e baratos para pular. Procure eles quando estiver deixando uma nota pela qual o leitor vai te agradecer — uma razão sutil pela qual algo funciona, um link para uma issue, um aviso sobre um caso extremo. Use docstrings quando estiver definindo uma função ou classe. Fora isso, deixe nomes claros e funções pequenas fazerem a conversa.

Você agora tem tudo que precisa para ler e escrever um arquivo Python. O próximo capítulo é onde a linguagem começa de fato a fazer coisas: variáveis, tipos de dados e os valores que o Python pode guardar.