Odores e Heurísticas - Comentários
Principais pontos sobre Comentários:
Evite Comentários Desnecessários
Comentários não devem ser usados para explicar código confuso. O ideal é que o código seja autoexplicativo por meio de bons nomes de variáveis, funções e classes.
Se um trecho de código precisa de um comentário para ser compreendido, talvez ele deva ser refatorado.
Comentários Enganosos
Comentários podem se tornar desatualizados e inconsistentes, especialmente quando o código muda e os comentários não são atualizados.
Um comentário errado é pior do que a ausência de um comentário, pois leva os desenvolvedores a conclusões erradas.
Bons Comentários
Comentários legais: Quando um comentário adiciona contexto ou história relevante sobre uma decisão de design.
Comentários de "To-Do": Indicam melhorias ou correções a serem feitas no futuro.
Comentários explicativos: Em casos raros, pode ser útil explicar o porquê de uma abordagem complexa (mas nunca para explicar o que o código faz).
Maus Comentários
Comentários redundantes: Apenas repetem o que já está claro no código.
Comentários ruidosos: Adicionam texto sem valor real.
Javadocs desnecessários: Se uma função tem um nome claro e simples, documentá-la pode ser redundante.
Código Limpo Reduz a Necessidade de Comentários
Um código bem estruturado e com bons nomes elimina a necessidade da maioria dos comentários.
Prefira refatorar um código confuso em vez de adicionar um comentário para explicá-lo.