Código limpo: Comentários

ComentáriosCódigo Limpo

Capítulo 4

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

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;

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)

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.

Comentários Ruins

● Murmúrios;

●

Comentários Ruins

●

Comentários Ruins

● Comentários enganadores;Criam confusão em relação a função do

código.● Comentários imperativos;

Comentários Ruins

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

Comentários Ruins

● Comentários ruidosos;

Comentários Ruins

● Marcadores de posição;

● Comentários nas chaves de fechamento;

Comentários Ruins

● Créditos de autoria

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;

Dúvidas!

?