Comentários no código: o que o Python ignora e você não deveria

O símbolo que o Python pula

Você já cruzou com o símbolo # em vários exemplos deste curso, marcando explicações dentro dos códigos. Hora de oficializar: esse símbolo, a cerquilha, cria um comentário. Da cerquilha até o fim da linha, o interpretador não lê nada; para ele, é como se o texto não existisse. O comentário é um canal exclusivo entre você e os humanos que lerão o código, incluindo o mais importante deles: você mesmo, daqui a três meses, sem lembrar de nada.

# Este programa monta a abertura do cartão de visitas
print("==============================")
print("Ana Lima")  # o nome vem primeiro, em destaque

# Saída: apenas as duas linhas do print. Os comentários não aparecem.

Comentário em linha própria e comentário no fim da linha: as duas formas valem.

Repare nas duas posições possíveis. O comentário de linha inteira, acima do código, apresenta um bloco ou uma decisão. O comentário de fim de linha acrescenta uma nota curta à instrução ao lado. Convém não exagerar no segundo tipo: nota lateral comprida empurra a linha para além da tela e vira leitura ruim. Havendo muito a dizer, diga em linha própria, antes do código.

Comentário bom explica o porquê, não o óbvio

Existe uma régua simples para separar comentário útil de comentário inútil: o código já mostra O QUE ele faz; o comentário existe para registrar o que o código não consegue mostrar, que é o PORQUÊ. Motivo de uma escolha, aviso sobre uma pegadinha, contexto que não cabe em código. Comentário que apenas traduz a linha ao lado é eco: ocupa espaço, exige manutenção e não informa nada.

Os exemplos da coluna da direita contam coisas que o código sozinho jamais contaria: uma intenção de leitura, uma relação de tamanho, uma restrição de layout, um registro de teste. É esse tipo de anotação que salva tempo de verdade. Nos seus programas deste módulo, experimente escrever um único comentário de porquê no topo do arquivo, dizendo o que o programa faz e por que existe. Já é hábito de gente grande.

Desativar uma linha em teste, e o limite do bom senso

O comentário tem um segundo emprego, mais tático: desativar uma linha sem apagá-la. Basta pôr # na frente, e a linha hiberna; o interpretador passa reto. É o jeito clássico de testar duas versões de uma mensagem, guardar uma tentativa antiga por segurança ou isolar a linha suspeita de causar um erro. Quando decidir, você apaga a linha adormecida ou reativa removendo a cerquilha.

print("Programando um dia de cada vez")
# print("A persistência vence o talento")  # versão antiga, guardada para comparar

A segunda frase está desativada: o programa mostra só a primeira. Trocar a cerquilha de linha inverte o teste.

Por fim, o limite. Comentário é tempero, não prato principal. Um arquivo em que toda linha carrega legenda fica mais difícil de ler, não mais fácil: o olho precisa filtrar o ruído para achar o código. E há um risco sorrateiro: código muda e comentário esquecido não muda junto; meses depois, a anotação mente sobre a linha ao lado, e comentário mentiroso é pior que nenhum. A meta, que a próxima aula desenvolve, é escrever código tão claro que precise de poucas anotações, e reservar o comentário para o que só ele sabe dizer.