Interessante estas sugestões escritas pelo Prof. Feofiloff.
Só para acrescentar:
Comentários no meio do código cheiram a refatoração:
http://wiki.java.net/bin/view/People/SmellsToRefactorings
(o que é refatoração: http://www.refactoring.com/)
A indústria tem bons exemplos de boa documentação. A própria API do java é uma (o que é alcançado através do javadoc).
Forum