A frase que mudou meu jeito de programar

No início de 2017 eu encontrei uma postagem no Facebook com uma frase que marcou o jeito que eu desenvolvo software. A frase é a seguinte:

"When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous."

O autor dessa frase é Martin Fowler, um profissional especializado em projetar e desenvolver software com técnicas ágeis. Ele é autor de vários livros, realiza palestras e é reconhecido internacionalmente.

Basicamente essa frase diz que quando você sentir a necessidade de escrever um comentário no seu código, você inicialmente deve refatorá-lo e posteriormente nenhum comentário será necessário .

E a documentação do código?

Em um primeiro momento eu gostei da frase, mas confesso que também fiquei receoso. Logo me veio o seguinte pensamento: E a documentação do código como fica?

Foi quando eu me lembrei que um dos principais valores do método ágil XP é produzir código de alta qualidade e de fácil leitura. Partindo desse princípio, outras documentações complementares se tornam desnecessárias e isso vai ao encontro da frase de Martin Fowler.

E na prática? Será que funciona?

Faz mais de 2 anos que coloco isso prática e funciona muito bem. No início, você escreve um código e pensa: Preciso inserir um comentário, pois talvez no futuro eu não consiga entender. É nesse momento que a frase precisa ser lembrada.

Caso você tenha um código que talvez você (ou outra pessoa) não entenda futuramente, há um claro indício que seu código não está bom. Aqui temos um ótimo momento para colocar a refatoração em prática.

Atualmente, eu nem penso mais em comentar um código. Quando eu termino algum método ou rotina, se o código não está bom, imediatamente eu começo a refatorar. Por incrível que pareça isso não leva tanto tempo e caso você não refatore, com certeza futuramente alguém gastará muito mais tempo corrigindo os bugs gerados por esta rotina.

Cuidado para não exagerar

Sempre que compartilho isso com outras pessoas, estou falando de colegas de profissão e dos meus alunos, sempre tem alguém que fala:

• O Netbeans/VSCode/Atom/IDE's geram muitos comentários automaticamente.
• E as annotations como ficam?

Eu particularmente, não gosto nem desse tipo de comentário, as minhas justificativas são:

• Comentários sobre o autor e as modificações no código devem ficar no controle de versão.
• Annotations para documentar argumentos e seus tipos: Para quem gosta de uma tipagem explícita, recomendo usar uma linguagem que faça nativamente isso.

Embora não seja a minha preferência, também não condeno. A grande questão é que você não pode exagerar. Isso é uma dica para aqueles programadores que fazem um código ruim e tentam "justificá-lo" ou "deixá-lo melhor" inserindo comentários.

Independente da linguagem e dos padrões que você utiliza, o importante é sempre produzir bons códigos e essa é a essência da frase de Martin Folwer.

Dúvidas ou sugestões é só entrar em contato. Abraço.