Clean Code – COMENTÁRIOS

Comentários devem ser evitados, uma vez que devemos nos expressar através do nosso código e uma das motivações mais comuns para criação de comentários é um código ruim.

• Comentários compensam um código ruim: Códigos claros e expressivos com poucos comentários são de longe superiores a um amontoado de e complexo com muitos comentários.

• Comentários bons: O único comentário bom é aquele que encontramos uma forma de não escrevê-lo.

• Comentários legais: Às vezes, por questões corporativas somos obrigados a colocar informações legais no nosso código. Comentários como esse não devem conter termos e contratos legais. O ideal é fazer referência a uma licença padrão.

• Comentários informativos: Um comentário que explica como uma função se comporta, em alguns casos pode ser válido, como no exemplo abaixo. Ex.:
  // Formato kk:mm:ss EEE, MMM dd, aaaa
Pattern match = Pattern compile.("\\d*:\\d*:\\d*\\w*,\\w*\\d*,\\d*");
  Neste caso, o comentário nos esclarece a expressão regular.

• Destaque: Pode-se usar um comentário para sinalizar algo importante que possa passar despercebido.

• Comentários enganadores: Comentários podem ser enganadores uma vez que tendemos a ignorá-los. Com isso, podem ser passadas pequenas desinformações sobre o código.

• Comentários ao lado de chaves de fechamento: Se virmos a necessidade de colocar um comentário destes, antes, devemos tentar reduzir nossas funções.

• Créditos e autoria: Não devemos poluir o código com comentários de autoria. O ideal é que o código seja versionado de forma que possamos saber o autor.

• Informações não-locais: Se for necessário escrever um comentário, coloque-o perto do código que o descreve.

Vale à pena sempre ponderar a necessidade do comentário, mas pense que não compensa o esforço para quem terá de fazer a manutenção.