Simples Getter / comentários Setter

Question

O que convenção que você usa para comentar getters e setters? Isso é algo que eu me perguntei por 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 muito bem escrever exatamente a mesma coisa para 1a / b e 2a / b, algo como 1-A) Define o salário do empregado, 1b) do salário do empregado. Ele parece tão redundante. Agora eu podia ver para algo mais complexo que você pode escrever mais nos (a) partes, para dar contexto, mas para a maioria dos getters / setters lá fora, o texto é quase exatamente o mesmo.

Eu sou apenas curioso para saber se, para os getters simples / setters sua ok apenas para preencher tanto o (a) parte ou (b) parte.

O que você acha?

Answer 1

Eu normalmente apenas preencher a parte param para setters, ea 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();

Assim javadoc ferramentas de verificação (tais como avisos do Eclipse) sairá limpo, e não há nenhuma duplicação.

Answer 2

Absolutamente inútil - você está melhor sem esse tipo de porcaria bagunçando seu código:

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

Muito útil, se justifica:

/**
 * 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 meios pode ser crucial para modelos de domínio. Sempre que vejo um feijão cheio de propriedades com nomes obscuros que os banqueiros única de investimento, bioquímicos ou físicos quânticos entender e os comentários explicam que o método setGobbledygook () "define o gobbledygook.", Eu quero estrangular alguém.

Answer 3

Geralmente nada, se eu puder ajudá-lo. Getters e setters deve ser auto-explicativo.

Eu sei que soa como uma não-resposta, mas eu tento usar meu tempo para comentar coisas que precisam de explicação.

Answer 4

Eu diria que só se preocupam com comentando getters e setters se eles têm algum tipo de efeito colateral, ou exigir algum tipo de fora condição de inicialização (ou seja: obter irá remover um item de uma estrutura de dados, ou a fim de set algo que você precisa ter x e y no lugar primeiro). Caso contrário, os comentários aqui são bastante redundante.

Edit: Além disso, se você encontrar um monte de efeitos colaterais estão envolvidos em seu getter / setter, você pode querer mudar o getter / setter de ter um nome método diferente (ou seja: empurrar e pop para uma pilha) [Obrigado pelos comentários abaixo]

Answer 5

Pergunte a si mesmo o que você quer que as pessoas vejam quando os comentários são vistos como JavaDocs (a partir de um navegador). Muitas pessoas dizem que a documentação não é necessária, uma vez que é óbvio. Isso não vai segurar se o campo é privado (a menos que você ligar explicitamente JavaDocs para campos privados).

No seu caso:

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

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

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

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

A primeira linha diz ele retorna a altura. Os documentos de parâmetros de retorno que altura está em metros.

Answer 6

Por que eles não apenas incluir uma tag de referência para deixá-lo comentar o valor do campo ea 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;
}

Assim que a documentação aplica-se ao getter e setter, bem como o campo (se javadocs privadas está ligado que é).

Answer 7

Este tipo de clichê pode ser evitado usando Projeto Lombok . Apenas documentar a variável de campo, mesmo que seja private, e deixe anotações Lombok gerar getters e setters devidamente documentados.

Para mim, só este benefício vale a pena o .

Answer 8

Estou realmente decepcionado com as respostas basicamente dizendo documentação abrangente é um desperdício de tempo. Como são clientes de sua API deveria saber que um método chamado setX é uma padrão setter propriedade JavaBean , a menos você dizê-lo claramente na documentação ?

Sem documentação, um chamador teria nenhuma idéia se o método teve quaisquer efeitos secundários, excepto cruzando os dedos sobre a convenção aparente sendo seguido.

Eu tenho certeza que não sou o único aqui para ter tido a infelicidade de descobrir a maneira mais difícil que um método chamado setX faz muito mais do que apenas definir uma propriedade.

Answer 9

Se não houver operação especial no getter / setter Eu costumo escrever:

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 extrato privada):

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

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

Answer 10

Comentando acessores, especialmente se eles não fazem qualquer operação em qualquer lugar, é desnecessário e um desperdício de alcance.

Se alguém ler o seu código não pode compreender que person.getFirstName() retorna o primeiro nome de uma pessoa, você deve tentar tudo em seu poder para tirá-lo demitido. Se ele faz alguma mágica banco de dados, lança alguns dados, chama o Secretário de Nomes para obter o primeiro nome, é seguro assumir que é uma operação não-trivial, e documento-lo bem.

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

Answer 11

Não coloque nada se o nome do campo é suficiently descritivo do conteúdo.

Geralmente, deixe o código ser auto pé, e evitar comentar se possível. Isso pode exigir refatoração.

EDIT: A descrição acima refere-se apenas aos getters e formadores. Eu acredito que qualquer coisa não trivial devem ser devidamente javadoc'ed.

Answer 12

é ok para preencher o (b) parte, especialmente se você colocar um comentário na declaração de campo indicando que o campo está em causa.

Answer 13

Se o javadoc não acrescenta nada, eu apagar o javadoc e usar os comentários gerados automaticamente.

Answer 14

Eu sempre preencher ambos. O tempo de digitação passou adicional é insignificante, e mais informação é melhor do que menos, em geral.

Answer 15

Se é um getter / setter, deve ser documentada.

eu discordo aqui, mas se ele pode ser feito de um imóvel, talvez seja melhor para simples codificação dos usuários da classe. Eu discordo mais, mas como para todos os comentários que têm "java" em qualquer parte deles, que disse que era java? (As tags, mas a questão poderia aplicar em qualquer lugar realmente)