Metaforando, uma análise não-funcional

Atenção: Todas as piadas são referências ao canal metaforando, do Vitor Santos.

Eu sou Daniel Belintani, perito não-profissional de micro expressões regulares.

“Código nunca mente. Já os comentários as vezes o fazem.”

Acredito que a primeira vez que eu vi esta frase foi em 2009, e naquele momento a minha cabeça explodiu! Desde então, nunca mais documentei um código "só por documentar". Ao procurar o texto original e atribuir corretamente os louros ao seu criado(a), só encontrei o famoso Ron Jeffries, quando divulgou a frase ao tweetar, em 2018.

Diagnosticando um cenário, na prática, sobre uma função que irá finalizar um carrinho de compras.

Até o momento, a análise realmente prova de que os comentários mostram descritivos congruentes. Apesar destes comentários serem completamente inúteis dado a sua redundância.

Seria aceitável que este código na sequência precise começar a verificar se o carrinho não está vazio:

Conforme o protocolo SPAMS, podemos observar que o descritivo da função "finaliza um carrinho, ou mostra mensagem de erro" já apresenta o seu primeiro comportamento incongruente. Fica evidente a inexistência de um comentário direto, onde função evita dizer: "eu retorno warning". Isso poder ser justificado por um simples esquecimento dos fatos pelo(a) programador(a).

Esta alteração no código também apresentou uma expressão de IDH (início de um histórico) na L9 seguido de um FDH (fim de histórico) na L14. O que de fato, não é um comentário bem-visto pela comunidade, sendo que há controladores de versão (ex: git) para exercer tal função.

Os comentários são então removidos no PR (pull request), mas alguns meses depois, um BUG traz uma nova pessoa para este código, e sem nenhum apego emocional, temos a alteração abaixo:

Vemos então um comentário desesperado, guiado pelo sentimento de vergonha ao fazer uma gambiarra desnecessária. É comum que pessoas culpadas deixem comentários como rastro dos seus crimes, na crença de que ganhou um "passe-livre da prisão" ao justificar-se com um comentário.

Outro comportamento de um comentário que tende a ser mentiroso, é o excesso de tensão textão, onde é adicionado um comentário longo para que ninguém leia. Este comentário, muito provavelmente não sofrerá a devida alteração quando algo mudar na regra de negócio.

Desconfie também de comentários que forçam a sua IDE (ferramenta de escrever código) a minimizar parte de códigos, isso pode ser considerado "afastamento e quebra de contato visual", muito utilizado por truques de mágicas.

Comentários podem ser mentirosos. Cuidado. Porém, existem comentários úteis:

• Comentários em acessos públicos. Se o código for "fechado", seja num servidor, ou em uma SDK, quem desenvolveu tem o dever de documentar e manter atualizado a explicação de como utilizar e qual a sua função. Para APIs a solução mais comum é o swagger.
• Comentários de TODO. Nunca deixe de anotar parte do código que ficou faltando algo ou que pode ser refatorado. Basta adicionar "TODO: o que fazer" nas linhas de referência.

Lembrando também que esse texto é um estudo, no qual venho na condição de perito dar uma visão, mas essa não é uma cartada final muito menos a verdade absoluta, é apenas uma análise.