O documento discute boas e más práticas de comentários em código. É recomendado reescrever código ruim em vez de comentá-lo. Comentários devem explicar a intenção do código de forma concisa e devem ser atualizados quando o código mudar. Comentários ruins incluem aqueles que são enganosos, longos demais ou tentam explicar o código em si.

1. Comentários
Código Limpo
Capítulo 4

2. Comentários
● “Don’t comment bad code—rewrite it.”;
● Se precisa de comentários, revise o código e
tente expressá-lo através dele;
● Fontes de imprecisão

3. Cuidados
● Vida útil do comentário;
○ Comentário que não é atualizado juntamente com as
mudanças que ocorrem no código.
● Localização do comentário;

4. Comentários
Comentários Compensam
um Código Ruim
// Verifica se o funcionário tem direito a todos os
beneficios
if ((empregado.flags & HOURLY_FLAG) &&
(empregado.age > 65))
if (empregado.isElegivelParaTodosBeneficios)

5. E onde o comentário é BOM?
● Questões legais; (Direitos autorais)
● Comentários informativos;
○ Funções
○ Patterns
● Explicação da Intenção;
● Esclarecimento;
(assertTrue(a.compareTo(a) == 0); //a==a)
● Alerta sobre consequências;
● Comentário TODO;
● Destaque;
● JavaDoc e outras API's.

6. Comentários Ruins
● Murmúrios;

7. Comentários Ruins
●

8. Comentários Ruins
● Comentários enganadores;
Criam confusão em relação a função do
código.
● Comentários imperativos;

9. Comentários Ruins
● Comentários longos;
Deve-se evitar códigos muitos longos

10. Comentários Ruins
● Comentários ruidosos;

11. Comentários Ruins
● Marcadores de posição;
● Comentários nas chaves de fechamento;

12. Comentários Ruins
● Créditos de autoria

13. Comentários Ruins
● Explicar código em comentários;
● Comentários HTML;
● Informações não locais;
● Informações excessivas;
● Conexões não obvias;
● Cabeçalhos de funções;
● Java docs em códigos não públicos;

14. Dúvidas!
?