[Clean Code] – Tome cuidado com seus comentários!
FILED IN Clean Code Sem comentários
Sim, comentários são tentadores, mas podem arruinar seu código e acabar com sua reputação. Digamos que o comentário é um mal necessário e pode nos nortear em determinadas ocasiões mas, dependendo de como, quando e onde ele for colocado, pode nos atrapalhar e muito.
Não use comentários como muleta:
O comentário não pode servir de muleta para códigos ruins e em 90% dos casos eles são adicionados por esse motivo. Precisamos ler um código da mesma maneira que lemos um livro, repare que em muitos livros existem comentários no rodapé e, sem esses comentários, ficaria complicado entender a citação do autor.
“Explique-se e não complique-se”:
Antes de adicionar um comentário, analise o código e verifique o que você pode mudar para que ele não precise de explicações. Se depois de analisar e “refatorar” seu código você ainda sentir necessidade de incluir um comentário, seja muito claro e direto ao inseri-lo. Nunca, em hipótese alguma inclua comentários como:
// Verifica se $usuário é igual a fernando
if($usuario == 'fernando'){
...
}
// Data e hora
date("d/m/Y H:i:s");
Precisava realmente desses comentários?
Chaves de fechamento:
Esse é um erro que eu cometi durante muito tempo, sempre com a grande desculpa de que a IDE que eu usava não indicava o fechamento para a minha função. Mas quando começamos a entender a importância de “refatorar” nossos códigos e vemos que a nossa função, por exemplo, precisa de um comentário para identificar seu fechamento é sinal de que algo está errado!
public function adicionarNomeUsuario($nome){
...
}//public function adicionarNomeUsuario($nome)
Longos e intermináveis comentários:
Acredite, ainda existem pessoas que, ao editar um módulo, adicionam um comentário no início para informar o que foi modificado. Com o passar do tempo, esse comentário parecerá uma redação e perderá completamente seu sentido, servindo apenas para confundir e irritar quem abrir o arquivo.
Depois desse breve post, lembre-se de que comentários não são obrigatórios e eles podem atrapalhar mais do que ajudar. Caso precise adicionar algum comentário perca tempo para faze-lo bem e use o bom senso!
