Odores e Heurísticas - Comentários

Principais pontos sobre Comentários:

1. 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.

2. 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.

3. 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).

4. 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.

5. 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.