Código Limpo — Comentários

Seguindo nossa saga de apresentar os primeiros conceitos de Código Limpo, hoje nós vamos falar sobre os nossos queridos comentários. Se você não leu o primeiro ou o segundo texto, além de recomendar a leitura, gostaria de já informar que tudo que será escrito aqui não tem por objetivo inventar algo novo. Todas as informações aqui expostas estão presentes no livro Código Limpo, apenas estou apresentando uma síntese de alguns pontos para encorajá-los a ler este livro que mudou a história de muitos programadores.

Comentar nossos códigos é algo corriqueiro, seja para nos ajudar num futuro próximo ou para explicar aos nossos colegas o que fizemos. Mas será que é a melhor maneira de se expressar?!

Comentários são sempre fracassos

O autor é sucinto ao responder essa questão. Quando fazemos um comentário em nosso código o fazemos por um motivo, nos expressar melhor. Por mais que usemos linguagens de alto nível, ainda assim são códigos então é natural que comentários sejam necessários. Queremos nos expressar melhor para que nossos colegas possam entender e contribuir na construção de nosso código mas comentar nem sempre é o melhor caminho.

Na verdade devemos nos esforçar ao máximo para melhorar nosso código para que ele seja a melhor expressão. Eu sei que as vezes não será possível evitar comentários mas nosso objetivo principal deve ser otimizar e melhorar nosso código, sem pegar o caminho mais fácil fazendo um comentário.

Como uma bússola o autor nos apresenta quando pode ser útil comentar e quando não devemos comentar.

Comentários Positivos

Em projetos reais é necessário deixar as informações legais, como direitos autorais, licenças e outras competências desta natureza. Então não há muito o que dizer, você deve colocar em seu código essas informações em forma de comentários para se resguardar.

Comentários positivos são comentários que podem auxiliar a você e ao seu time no decorrer do tempo. Comentários como explicar a intenção de algo, esclarecimentos acerca de determinadas funções particulares de bibliotecas que estão sendo usadas, alertar sobre possíveis consequências de se alterar determinada função, destacar detalhes que são fundamentais ao projeto e outros comentários deste gênero.

Comentários Negativos

O pior de todos os comentários possíveis com certeza são comentários de murmúrio. Comentar reclamando que o código está estranho ou mal feito porque estava com pressa, se for fazer algo faça direito.

Comentários que não levam a lugar nenhum devem ser evitados. Comentários redundantes ou que confundem mais do que ajudam, são inúteis. Se o seu código está mais claro do que o comentário, por quê comentar?!

Se seu comentário é longo, provavelmente é porque seu código está muito confuso então é melhor refatorar do que tentar explicar. Tenha em mente que o seu objetivo é construir um código limpo.

Estes comentários confusos e enganadores se tornam ruídos no processo de programar. Comentários devem ser claros, simples, diretos e de preferência não devem existir.

Conclusão

Assim como nas redes sociais, comentar um código é algo necessário mas que deve ser feito com consciência e cuidado. Não queremos estragar nossa obra de arte com comentários ruins e inúteis.

Este foi o último texto da nossa saga, espero que tenha percebido como é importante construir um bom código. Se não leu os outros textos pode procurar na publicação 20 21 que estarão todos lá.