Documentar código

Programação Arquitetura
#1

alguém costuma documentar getters/setter?

/**@return the attribute var*/
public int getVar {
return var;
}

#2

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

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

#3

[quote=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.[/quote]

faço o mesmo…

#4

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

[code]/**
*

  • @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{
[/code]
Pra um getter/setter documento assim mas por causa do CheckStyle na Empresa:

[code]/**

  • @param String string
  • @return String
    */

public String getValorTotal(){
return valorTotal;
}

/**

  • @param String string
    */

public void setValorTotal(String string){
valorTotal = string;
}
[/code]

#5

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

#6

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?

#7

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”.

#8

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]

#9

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

#10

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

#11

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

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

#12

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

#13