Comentários podem ser umas das piores coisas a encontrar no código, e nunca devem de ser usados. Bem, não é bem nunca, até há situações em que um comentário no sitio certo, pode ser uma excelente ajuda, mas regra geral fazem mais mal do que bem.
Existem alguns motivos pelo qual eu não gosto de comentários no código. Uma das razões é que acabam por ser mais “linhas de código” para navegar. Não digo isto porque acho que bom código é escrever o menor número de linhas, mas esta discussão fica para outro post ;). Por exemplo, se tivermos uma classe com 4 ou 5 métodos e cada métodos tiver umas 5 linhas de comentários temos logo mais, 20 linhas para andar a fazer scroll para cima e para baixo. Não é a razão principal, mas admito que é uma coisa que me incomoda um pouco. Para mim a principal razão é que é mais uma linha de código para manter. Vamos imaginar que temos a seguinte função que devolve sempre o primeiro elemento de uma lista de inteiros.
Agora vamos imaginar que há uma mudança de requisitos no nosso programa e no lugar de devolver o primeiro deve devolver o segundo elemento de uma lista. Acontece que o código é alterado, mas por alguma razão esquece de alterar também o comentário. Agora temos uma função que devolve o segundo elemento, mas o comentário induz em erro pensando que devolve o primeiro elemento. Tens razão, podemos contra argumentar que é só mais uma linhas e que não esquece, mas no dia a dia existem sempre várias distrações quer queiramos quer não e o mais provável é que isso vá acontecer eventualmente em algum momento.
Outra razão razão é que nos torna preguiçosos a nomear as funções e variáveis. O nome GetElement(…) para uma função não é muito explicito, poderia ser melhorado. Se chamassemos de GetSecondElementFromList(…) não seria preciso nenhum comentário. Acredito que é sempre benéfico perder mais uns segundos a dar um bom nome a uma função do que inserir um comentário.
Quando escrevo código a minha abordagem é nunca utilizar comentários, mas existem algumas raras excepções em que um comentário pode dar muito jeito. Na minha opinião os comentários não devem de descrever o que a função faz, pode no máximo descrever o porquê da implementação. Um bom exemplo seria o comentário que se segue. Neste caso, apesar de não utilizar o melhor método para ordenar a lista, a nível de performance não é critico. Isto previne que alguém perca muito tempo a tentar optimizar algo desnecessário.
Outra situação que por vezes gosto de usar os comentários é para adicionar TODOs de coisas que são necessárias fazer, mas que não são o foco no momento. Por exemplo a navegar pelo código encontro um método que pode ser melhorado, adiciona o TODO e continuo aquilo que estava a fazer. No fim posso voltar ao TODO e fazer o refactor do método.
Regra geral considero que os comentários são maus, torna-nos preguiçosos porque muitas das vezes podemos renomear as coisas e deixam de ser necessários comentários. Acabam por criar ruído no código quando temos um code base muito grande e são mais uma coisa a manter além do próprio código. Contudo existem algumas situações em que podemos utilizar comentários para explicar o porquê de adoptar uma solução no lugar de outra.