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