Documentar código

Não costumo documentar getter/setter não.

Depois que o eclipse gera, os que não tiverem validação nenhuma, nem mecho neles.

paulohrl:

Não costumo documentar getter/setter não.

Depois que o eclipse gera, os que não tiverem validação nenhuma, nem mecho neles.

faço o mesmo…

Sempre usando as tags e uma descrição rápida.

/**
 * 
 * @param AplicacaoWebVO aplicacaoVo
 * @throws RTPException
 * @throws RFBException
 * @throws MIException
 * comentários: A partir de um objeto AplicaoWebVO efetua uma aplicação através de um
 * 				serviço RTP.
 */

public void executeAplicacao(AplicacaoWebVO aplicacaoVo) throws RTPException, RFBException, MIException{

/**
 * @param String string
 * @return String
 */

 public String getValorTotal(){
    return valorTotal;
  }

/**
 * @param String string
 */

 public void setValorTotal(String string){
    valorTotal = string;
}

Getters e Setters não.
Quanto ao restante, depende da aplicação. Se estiver sendo feita em inglês, documento em inglês.

getter e setter eu não comento pois, parto do princípio que qualquer programador que nunca viu o código, bate o olho num método desses e ja sabe pra q q serve, então pra q comentar?

Uma coisa que acho desajeitada é que não há suporte para getters e setters no Javadoc. No mínimo deveria haver algo como:

/**
 * @property A fonte das legendas. 
 */
private Font font;

public void setFont (Font font) { this.font = font; }
public Font getFont () { return font; }
/**
 * @property O nome do aplicativo.
 */
private String nome;
public String getNome() { return nome; }

E na documentação deveria aparecer:

É claro que se pode escrever um doclet que faça isso por mim, mas não é uma coisa “padrão”.

Documentar setters e getters que fazem apenas a atribuição é algo que só se justificaria devido ao jugo de um CheckStyle da vida.

[edit]Quanto à questão da língua: código em português, documentação em português; código em inglês, documentação em inglês.[/edit]

getter e setter tambem não costumo comentar…
apenas se for algo de muita importancia conceitual no sistema…
[]´s

Rodrigo Manhães
"Quanto à questão da língua: código em português, documentação em português; código em inglês, documentação em inglês."

Como a linguagem é toda em inglês tenho preferência por documentar em inglês. Acho que fica mais simples, pois não preciso ficar colocando detalhes como JTable.getRow() (pegarLinha), em inglês o cara já tá vendo o nome do método, e se o cara não souber inglês nem o javadoc ele vai ler…rs daí num tem como…

Dicas sobre documentação:
http://www.ibm.com/developerworks/library/j-jtp0821.html

Documento em ingles, senão o resto do time não irá entender

Até mesmo projetos pessoais (onde só eu mexo) documento em ingles.

Sobre getters and setters, eu não comento não. No máximo aqueles comentários que o Eclipse/RAD geram quando eu mando criar os getters and setters.
O que eu costumo fazer, é deixar sempre os Getters and Setters no final do arqiuvo e colocar um comentario do tipo
//-- Getters and Setters

só para deixar claro onde é a fronteira dos métodos e dos getters and setters (eu também faço isso para Atributos).

Outra coisa que já até foi discutida aqui no GUJ é sobre documentação excessiva em código. Documentar é importante, mas nem tudo, senào fica muito dificil de atualizar a documentação depois.

Se utilizarmos nomes “auto-explicativos” em métodos, certamente iremos poupar um bom trabalho de documentação

Só para levantar uma bola. Fowler diz que documentar código é indicação de um mal cheiro logo, é passível de refatoração.

Documentar a interface de um método sempre me leva a pensar que o nome do método, o nome dos parâmetros, as declarações de exceções estão ruim. Quando a interface de um método esta legal vc olha para ela e já sabe o que o método faz e como utiliza-lo.

Documentações de métodos poderiam ser substituídas por métodos que tem suas responsabilidades bem definidas e bem expressadas pelo seu nome.

Porém, eu ainda continuo documentando métodos logo, meus métodos não tem uma responsabilidade bem definida ou esta responsabilidade não é bem expressada no seu nome ou ambas!

[]s