Utiliza-se Javadoc?

Foi criado exatamente para ajudar o desenvolvedor, mas já vi muito projeto que não colocam comentários nos métodos, o que é horrível ficar tentando adivinhar o que o método faz.
É a melhor forma de expor a interface dos seus objetos aos Clientes. Ah não ser que você seja muito maldoso e prefira que eles fucem no código fonte pra descobrir o que precisam.

Mais que o documento HTML gerado, comentários em JavaDoc ajudam muito nas IDEs.

Existem emrpesas com políticas rígidas sobre comentários, mas este tipod e ambiente costuma resultar em:

/** Retorna o nome */
public String getNome(){
...
}

:roll:

ASOBrasil…O javadoc pode ajudar em uma manutenção futura do sistema, e hoje em dia o javadoc jaz parte de padrões de metodologias, pois aqui na empresa que trabalho javadoc é obrigado pois seguimos o CMM.