Comentários simples do Getter / Setter

Que convenção você usa para comentar getters e setters? Isso é algo que eu me pergunto há algum tempo, por exemplo:

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

Eu sempre acho que estou escrevendo exatamente a mesma coisa para 1a / be 2a / b, algo como 1a) Define o salário do funcionário, 1b) o salário do funcionário. Parece tão redundante. Agora eu pude ver algo mais complexo que você pode escrever mais nas partes (a), para dar contexto, mas para a maioria dos getters / setters por aí, o texto é quase exatamente o mesmo.

Estou curioso para saber se, para os getters / setters simples, apenas é permitido preencher a parte (a) OU a parte (b).

O que você acha?

Normalmente, eu apenas preencheu a parte param para setters e a parte @return para getters:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

Dessa forma, as ferramentas de verificação do javadoc (como os avisos do Eclipse) ficarão limpas e não haverá duplicação.

Absolutamente inútil - você está melhor sem esse tipo de lixo que atravessa seu código:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

Muito útil, se necessário:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

Especialmente a explicação do que a propriedade realmente significa pode ser crucial nos modelos de domínio. Sempre que vejo um bean cheio de propriedades com nomes obscuros que apenas banqueiros, bioquímicos ou físicos quânticos entendem, e os comentários explicam que o método setGobbledygook () "define o gobbledygook". Quero estrangular alguém.

Geralmente nada, se eu puder ajudar. Getters e setters devem ser auto-explicativos.

Sei que parece uma não resposta, mas tento usar meu tempo para comentar coisas que precisam de explicação.

Eu diria que só se preocupe em comentar getters e setters se eles tiverem algum tipo de efeito colateral ou exigir algum tipo de pré-condição fora da inicialização (por exemplo: get irá remover um item de uma estrutura de dados ou para definir algo que você precisa para colocar xey no lugar primeiro). Caso contrário, os comentários aqui são bastante redundantes.

Editar: Além disso, se você encontrar muitos efeitos colaterais envolvidos no seu getter / setter, convém alterar o getter / setter para ter um nome de método diferente (por exemplo: push e pop para uma pilha) [Obrigado por os comentários abaixo]

Pergunte a si mesmo o que você deseja que as pessoas vejam quando os comentários são vistos como JavaDocs (de um navegador). Muitas pessoas dizem que a documentação não é necessária, pois é óbvia. Isso não será válido se o campo for privado (a menos que você ative explicitamente o JavaDocs para campos privados).

No seu caso:

public void setSalary(float s)
public float getSalary()

Não está claro em que salário é expresso. São centavos, dólares, libras, RMB?

Ao documentar setters / getters, gosto de separar o quê da codificação. Exemplo:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

A primeira linha diz que retorna a altura. O parâmetro de retorno documenta que a altura está em metros.

Por que eles não incluem apenas uma tag de referência para permitir que você comente o valor do campo e a referência de getters e setters.

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

Para que a documentação se aplique ao getter e setter, bem como ao campo (se javadocs particulares estiver ativado).

Esse tipo de clichê pode ser evitado usando o Project Lombok . Apenas documente a variável de campo, mesmo que sejaprivate , e permita que as anotações do Lombok gerem getters e setters adequadamente documentados.

Para mim, esse benefício por si só vale os custos .

Estou realmente decepcionado com as respostas, basicamente dizendo que a documentação abrangente é uma perda de tempo. Como os clientes de sua API devem saber que um método chamado setXé um configurador de propriedade JavaBean padrão, a menos que você o diga claramente na documentação ?

Sem documentação, o interlocutor não teria idéia se o método tivesse efeitos colaterais, a não ser cruzando os dedos sobre a aparente convenção que estava sendo seguida.

Tenho certeza de que não sou o único aqui a ter tido o infortúnio de descobrir da maneira mais difícil que um método chamado setXfaz muito mais do que apenas definir uma propriedade.

Se não houver operação especial no getter / setter, eu normalmente escrevo:

Com Javadoc (com opção privada):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

e / ou

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Com Doxygen (com opção de extração privada):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

Comentar os acessadores, especialmente se eles não fizerem operações em nenhum lugar, é desnecessário e é um desperdício de pontas dos dedos.

Se alguém lendo seu código não puder entender isso person.getFirstName() retorna o primeiro nome de uma pessoa, tente tudo o que estiver ao seu alcance para que seja demitido. Se ele faz alguma mágica no banco de dados, joga alguns dados, liga para o Secretário de Primeiro Nome para obter o primeiro nome, é seguro assumir que é uma operação não trivial e documentá-lo bem.

Se, por outro lado, o seu person.getFirstName()não retornar o primeiro nome de uma pessoa ... bem, não vamos lá, não é?

Não coloque nada se o nome do campo for suficientemente descritivo do conteúdo.

Geralmente, deixe o código autônomo e evite comentar, se possível. Isso pode exigir refatoração.

EDIT: O acima se refere apenas a getters e setters. Eu acredito que qualquer coisa não trivial deve ser devidamente javadoc'ed.

não há problema em preencher a parte (b), especialmente se você colocar um comentário na declaração do campo indicando o que é o campo.

Se o javadoc não adicionar nada, eu o excluo e uso os comentários gerados automaticamente.

Eu sempre preencho ambos. O tempo adicional gasto digitando é insignificante e, em geral, mais informações são melhores que menos.