Elimine os comentários

Comments are evil. Você provavelmente já deve ter ouvido isso. Comentários mentem. Eles enganam você. Eles querem te pegar.

Já usei muito comentário nos meus códigos. Muito mesmo. Mas, apesar de negar no início, tive que aceitar que isso é uma má prática. E eu vou te explicar o por quê. Depois de ler esse post, você poderá tirar suas próprias conclusões :)

Comentários mentem

Para que seu código seja considerado um Código Limpo, ele precisa ser legível, e qualquer programador que o leia precisa entender qual era a sua intenção com aquele código.

Aí você está codando um algoritmo mega complicado, e pensa:

Vou deixar uns comentários aqui, pro próximo programador que ler isso saiba o que eu quis dizer! Ou até pra que eu mesmo lembre do que eu estava fazendo daqui a alguns dias!

Agora responda pra mim: de todas as vezes que você já editou código na sua vida, onde tinha comentários falando sobre o que o código fazia, quantas vezes você leu o comentário? E quantas vezes você lembrou de atualizar o comentário, para que correspondesse ao seu novo código?

Você tem costume de fazer isso? Seus comentários refletem exatamente o código que você fez e alterou milhares de vezes depois? Duvido! E digo isso por experiência própria.

Comentários mentem, pois eles tem um tempo de vida muito curto. A probabilidade de você simplesmente ignorar um comentário - já que os editores normalmente os deixam em uma cor quase apagada - é muito grande.

Olhe esse exemplo:

1
2
3
4
5
6
/**
 * Sempre retorna true
 */
function isAvailable() {
  return false;
}

É um exemplo besta, mas serve para reflexão: será que, depois de mudar o retorno da função, você mudaria o comentário? Não, seja sincero! Pare e pense.
Óbvio que não! O comentário iria ficar pra sempre ali, naquela mentira, enganando a si mesmo e a quem se atrever a ler, servindo apenas como lixo para confundir.

Aí você me diz: Então como eu vou fazer pra lembrar daquele algoritmo dificílimo que eu escrevi? Se eu não comentar, amanhã eu já nem sei o que eu fiz!

Se isso acontece com você, provavelmente você está fazendo alguma coisa errada. Eu sei que é duro ouvir isso, mas é a realidade. Antes de querer me bater, respire, pense… e aceite, pois é a realidade.

Um amigo me disse o seguinte sobre comentários:

Você só deve usar comentários no seu código se ele estiver tão ruim, mas tão ruim, que nem você consiga entender o que você fez.

Você precisa pensar assim: “Não consegui escrever um código decente e legível, sou um derrotado pois vou precisar escrever um comentário para dizer o que o meu código faz!”

Eu sei que é bastante duro, talvez você só compreenda com o tempo, mas é necessário entender o mal que faz um comentário no seu código.

Mas eu só comento no final das minhas funções, pois elas ficam muito grandes e eu precisaria usar a rolagem para saber qual é a função que está terminando naquele fechamento de chaves!

Se a sua função está ficando tão grande, a ponto de você precisar comentar no final dela, é sinal de que ela precisa de um refactory. Deixe-a mais enxuta. Ela provavelmente tem muitas responsabilidades e faz mais de uma coisa. Quebre em funções menores. Vai facilitar muito a sua leitura.

Imagine esse código:

1
2
// Verifica se o empregado tem direito aos benefícios
if( ( employee.flags && HOURLY_FLAG ) && ( employee.age > 65 ) )

Porque já não escrever dessa forma:

1
if( employee.isElegibleForFullBenefits() )

Precisa de comentário pra saber o que está sendo testado nesse if? O método deixa a intenção muito clara. Com isso, podemos ver que comentários podem ser desculpas para código ruim. Na maior parte das vezes, podemos melhorar nosso código somente criando uma função / método, como feito acima.

Fazendo isso, você deixa seu código realmente limpo. Qualquer programador que ler seu código, vai conseguir facilmente entender o que você pretendia fazer :)

Já recomendei uma vez, mas recomendo novamente a leitura do livro Clean Code, que fala detalhadamente sobre esse assunto! Com certeza você será um programador um pouco melhor quando parar de usar comentários :D

Sei que é um assunto bastante polêmico, mas gostaria de ouvir de você: o que você pensa sobre comentários? Tem uma opinião diferente? Comente! Vamos fazer uma discussão saudável sobre o assunto ;)

Sobre o #1postperday: https://blog.da2k.com.br/2014/12/31/um-post-por-dia/

Tem alguma sugestão para os próximos posts do #1postperday? Deixe ela aqui: https://github.com/fdaciuk/fdaciuk.github.io/issues/1