Boas Práticas de Documentação

Uma boa prática de documentação é uma descrição da classe e em cada método um comentário explicando para que serve.
Encher o código de comentários(há programadores que fazem um comentário a cada linha) torna o código sujo, e de difícil leitura.

public boolean adicionar(Cliente cliente){ …}

ok, o método tem um nome descritivo e seu funcionamento parece obvio. Em todo o caso não custa nada colocar um javadoc explicando sucintamente o que ele faz e, principalmente, o que retorna. nem sempre os métodos são auto-explicativos.

Se você vai se comunicar com uma equipe externa, ou escrever um livro, ou fazer um trabalho acadêmico… use a UML.
Procure livros de UML e você vai ver quilos de diagramas e documentação.

Puxa, acabei de ver isso:

http://www.urubatan.com.br/pare-de-perder-tempo-escrevendo-documentacao-do-codigo-que-voce-escreveu-parte-1/

Esse blog do Urubutan é show de bola

lmorelato:

Pessoal estou iniciando o meus estudos em OO e gostaria de saber boas práticas para documentar classes e métodos.

Leandro

Javadoc…
Um exemplo de java doc no metodo que nossa amigo postou

/**
 * Tenta adicionar um cliente e retorna se esse cliente foi adicionado com sucesso
 * @param cliente o cliente a ser adicionado
 * @return se o cliente foi corretamente adicionado
 */
public boolean adicionar(Cliente cliente){ ...}

é um recurso bem interessante, principalmente em ides que lhe permitem (como no eclipse) ao passar o mouse por cima do metodo ele vai apresentar esses comentarios formatados. Outra ponto positivo é gerar depois o JavaDoc.

é bom saber essas dicas para quem esta começando ou quem esta já a tempo na área, pois muita gente não comenta codigo e depois acaba esquecendo o que faz e para que serve…

boas dicas!