Artigo original: Putting comments in code: the good, the bad, and the ugly.
Me interrompa agora se você já ouviu isso antes…
"O código bom é aquele que se autodocumenta."
Em mais de 20 anos escrevendo código como profissão, essa foi uma das expressões que eu mais ouvi.
É um clichê daqueles.
Assim como vários outros clichês, há um fundo de verdade aí. Essa verdade, contudo, já foi muito massacrada por pessoas que disseram a frase sem ter ideia do que ela significava.
É verdade? Com certeza.
Quer dizer que você jamais deve fazer comentários no seu próprio código? Não.
Neste artigo, veremos o que é bom, o que é mau e o que é simplesmente feio quando falamos em comentários no código.
Para começar, há dois tipos diferentes de comentários no código. Eu os chamo de comentários de documentação e comentários de esclarecimento.
Comentários de documentação
Os comentários da documentação destinam-se a qualquer pessoa que provavelmente consumirá seu código-fonte, mas que provavelmente não o lerá. Se você estiver criando uma biblioteca ou framework que outros desenvolvedores usarão, você precisará de alguma forma de documentação de API.
Quanto mais distante do código-fonte a documentação da API estiver, maior a probabilidade de ela se tornar desatualizada ou imprecisa ao longo do tempo. Uma boa estratégia para reduzir esse problema é incorporar a documentação diretamente no código e, em seguida, usar uma ferramenta para extraí-la.
Aqui temos um exemplo de comentário de documentação extraída de uma biblioteca conhecida do JavaScript, chamada Lodash (em inglês).
Se você comparar os comentários com o que está na documentação on-line (em inglês), perceberá uma correspondência exata.
Se você escrever comentários de documentação, deve garantir que eles sigam um padrão consistente e que sejam facilmente distinguíveis de quaisquer comentários de esclarecimento incluídos e que você também queira adicionar. Alguns padrões e ferramentas populares e bem suportados incluem JSDoc para JavaScript, DocFx para dotNet e JavaDoc para Java.
A desvantagem desses tipos de comentários é que eles podem tornar seu código muito "cheio de ruído" e mais difícil de ler para qualquer pessoa que esteja ativamente envolvida na manutenção do código. A boa notícia é que a maioria dos editores de código suporta o "dobramento de código", que nos permite recolher os comentários para que possamos nos concentrar no código.
Comentários de esclarecimento
Os comentários de esclarecimento destinam-se a qualquer pessoa (incluindo o seu futuro eu) que possa precisar de manter, refatorar ou estender o seu código.
Muitas vezes, um comentário de esclarecimento pode mostrar que o código "cheira mal". Ele pode significar que o seu código é muito complexo. Você deve se esforçar para remover comentários de esclarecimento e simplificar o código, porque "o código bom é aquele que se autodocumenta".
Aqui está um exemplo (em inglês) de um comentário de esclarecimento ruim – embora muito divertido.
/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);Em vez de decorar uma frase levemente confusa com uma rima inteligente — e em anfíbraco, surpreendentemente — o autor se daria muito melhor se tivesse se dedicado a uma função que tornasse o próprio código mais fácil de ler e de entender. Quem sabe se uma função chamada removerChaves chamasse outra função chamada limparOInput?
Não me entenda mal. Há momentos – especialmente quando você está passando por uma carga de trabalho esmagadora – em que colocar um pouco de humor pode ser bom para a alma. Porém, quando você escreve um comentário engraçado para compensar o código ruim, isso realmente torna as pessoas menos propensas a refatorar e corrigir o código mais tarde.
Você realmente quer ser o responsável por roubar de todos os futuros programadores a alegria de ler aquela pequena rima inteligente? A maioria dos programadores riria e seguiria em frente, ignorando o código que "cheira mal".
Há também momentos em que você se depara com um comentário que é redundante. Se o código já é simples e óbvio, não há necessidade de adicionar um comentário.
Por exemplo, evite usar algo como isto:
/*Define o valor do inteiro idade como 32*/int idade = 32;Ainda assim, há vezes em que, não importando o que você fez com o próprio código, um comentário de esclarecimento ainda é uma boa pedida.
Isso geralmente acontece quando é preciso adicionar um pouco de contexto a uma solução contraintuitiva.
Aqui, temos um bom exemplo do próprio Lodash:
function addSetEntry(set, value) {
/* Não retorne `set.add`, pois ele não é
encadeável no IE 11. */
set.add(value);
return set;
}Também há momentos em que, depois de muita reflexão e experimentação, verifica-se que a solução aparentemente ingênua para um problema é realmente a melhor. Nesses cenários, é quase inevitável que algum outro programador venha achando que é muito mais inteligente do que você e comece a mexer com o código, apenas para descobrir que o seu caminho foi o melhor o tempo todo.
Às vezes, esse outro programador é o seu eu futuro.
Nesses casos, o melhor é poupar tempo e constrangimento de todos e deixar um comentário.
O comentário provocativo abaixo captura esse cenário com perfeição:
/**Caro mantenedor: ao terminar de tentar 'otimizar' este programa e depois de perceber o erro terrível que cometeu, lembre-se de incrementar o seguinte contador como um aviso para a próxima vítima: total_de_horas_perdidas_aqui = 42**/O comentário acima tem mais a ver com ser engraçado do que ser útil. Você, no entanto, DEVE deixar um comentário alertando os outros para não buscarem alguma "solução melhor" aparentemente óbvia, se você já tentou diversas e viu que não davam certo. Quando você fizer isso, o comentário deve especificar qual solução você tentou e por que você decidiu não usá-la.
Aqui está um exemplo simples em JavaScript:
/* Não use o isFinite() global porque ele retorna true para valores nulos*/
Number.isFinite(value)O feio
Bem, já vimos o bom e o mau. Vamos, agora, ver o feio.
Infelizmente, há momentos em qualquer trabalho em que você se verá frustrado e quando você escreve código como profissão, pode ser tentador desabafar essa frustração em comentários no código.
Trabalhando com bases de código suficientes, você encontrará comentários que variam de cínicos e deprimentes a sombrios e maldosos.
Há alguns que podem parecer inofensivos… (original em inglês)
/*Este código é uma droga, você e eu sabemos disso. Apenas siga em frente e me xingue mais tarde.*/…e outros que são simplesmente maléficos (original em inglês)
/* Classe usada para contornar o fato de que o Richard é um idiota sem tamanho*/Essas coisas podem parecer engraçadas ou podem ajudar a liberar um pouco de frustração no momento, mas quando elas entram no código de produção, acabam fazendo com que o programador que as escreveu e seu empregador pareçam pouco profissionais e amargos.
Não faça isso.
Se gostou deste artigo, compartilhe-o com seus colegas de trabalho. Se quiser ler mais (em inglês) sobre o assunto do artigo, assine a newsletter semanal do autor no site Dev Mastery.