Comentários simples do Getter / Setter

124

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?

ThaDon
fonte
54
Como um aparte, por favor, não use float para nada monetário (como salário aqui), nunca. Veja, por exemplo, stackoverflow.com/questions/965831/…
Jonik
3
Use BigDecimal em vez disso.
Josep

Respostas:

83

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.

sleske
fonte
Você pode consertar o erro? "parte de
retorno
1
Também há um erro de digitação no comentário de employee (). Não é um comentário do JavaDoc.
Fostah 22/06/09
1
Concordo que é a melhor abordagem para comentar os acessadores.
Fostah
30
Adicionar ruído ao seu código para silenciar avisos excessivamente pedantes de nossas ferramentas parece errado para mim. Se não agregar valor a um programador, a solução certa seria recusar / corrigir a verbosidade das ferramentas e / ou diminuir o quanto nos preocupamos em pular os aros para que as ferramentas nos recompensem. As ferramentas de análise devem ajudar-nos e economizar esforço, não criar tarefas sem sentido para nós.
Lyle
1
@ Style Isso pode ser verdade, mas eu sinto que quase sempre há algo útil que um programador pode dizer que descreve um getter / setter melhor do que apenas a assinatura do método. Sim, há casos em que um programador é preguiçoso e apenas repete a assinatura do método no comentário, mas acho que, de um modo geral, é um comportamento útil forçar.
226148 Matt Vukas #
174

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.

Michael Borgwardt
fonte
2
Meus sentimentos exatamente, o pior são os modelos específicos de domínio, onde apenas um especialista em domínio sabe o que diabos a propriedade significa.
21420 ThaDon
7
Mesmo que seja útil, o que você faria para getFoo (). Você também copiará o mesmo comentário para o getFoo ()?
Vinoth Kumar CM
3
@cmv: Obviamente, a parte "param" não seria copiada. Não sei se o valor de ter as informações anexadas aos dois acessadores justifica a duplicação das informações. Provavelmente sim. Melhor ainda seria uma maneira de anexar um comentário a ambos; Acredito que isso esteja disponível no Projeto Lombok.
Michael Borgwardt
@ VinothKumar: talvez seja melhor explicar simplesmente a propriedade no getter (como em "Foo é o fator de ajuste usado no cálculo da barra") e os efeitos da alteração do valor no setter (ou se é necessário ou não para inicializar esse valor - no exemplo da resposta, não é necessário inicializar o Foo, pois "ele possui um valor padrão dependendo do tipo Baz").
freitass
+1 para "nomes obscuros que apenas banqueiros de investimento, bioquímicos ou físicos quânticos compreendem"
Jackson
36

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.

Eric Wendelin
fonte
5
Outra resposta válida ao longo destas linhas pode ser "projetos com getters e setters não compreender corretamente a noção de encapsulamento" :)
Trejkaz
2
@Trejkaz: Não é verdade, porque os métodos do acessador permitem propriedades somente leitura ou somente gravação e polimorfismo (e, portanto, quebra automática, proxy e assim por diante).
Laurent Pireyn
2
Eles podem permitir essas coisas, mas muitas vezes um padrão de construtor pode substituir setters (menos mutável) ou um padrão do visitante pode substituir getters (mais flexível.)
Trejkaz
Eu certamente gosto e uso o padrão de construtor, mas há tanto suporte para POJOs (por exemplo, no Hibernate) que getters e setters ainda têm seu lugar de destaque, para melhor ou para pior. É a coisa mais difícil sobre Java, IMHO, e depois de escrever JavaDocs repetitivos por mais de uma década, estou pronto para assinar os conselhos de @ sleske.
Michael Scheper
34

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]

Gopherkhan
fonte
10
indiscutivelmente, você deve alterar o nome dos getters que têm efeitos colaterais para ficar mais claro, pois nem todos os desenvolvedores lerão os comentários.
akf
Tudo bem - mas isso exige que os usuários da sua API saibam que, se houvesse efeitos colaterais, eles teriam sido documentados !
22125 oxbow_lakes
akf, eu estava pensando exatamente isso depois de postar :) Acho que vou adicioná-lo à minha resposta.
Gopherkhan
1
mas se você não documenta getters e idiotas "estúpidos" (é o que eu prefiro também!) - como você se livra dos avisos do Eclipse sobre o javadoc ausente? Eu não quero encher meu espaço de trabalho com avisos como esse, mas eu também não quero que a advertência deve ser desativado para todos os outros métodos ...
Zordid
12

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.

Steve Kuo
fonte
1
Embora eu concorde com você, acho que é preciso garantir que os comentários da função não estejam substituindo um nome de função não-explícito e mal escolhido.
karlipoppins
Sou um grande defensor do JavaDocs, mas também um grande defensor do código de auto-documentação. Então, pelo menos para o levantador, eu faria algo como public void setSalary(float aud)(ou mais realista public void setSalary(BigDecimal aud)). Melhor ainda, a propriedade deve ser do tipo abstract class CurrencyAmount, que por sua vez possui as propriedades java.util.Currency currencye java.math.BigDecimal amount. A maioria dos desenvolvedores com quem trabalhei são muito preguiçosos com o JavaDoc, mas aplicar APIs como essa torna isso menos um problema.
22313 Michael Scheper
Se a unidade é uma unidade SI como metros / segundo, há menos necessidade de documento, se não é uma unidade de Si, então ele deve ser documentado ou melhor chamado para incluir a unidade não padrão, por exemplo heightFeet
AlexWien
8

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

Steve
fonte
Concordo. E então eu percebi, por que escrever todo esse clichê de qualquer maneira? Veja minha resposta sobre o Projeto Lombok.
Michael Scheper
7

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 .

Michael Scheper
fonte
4

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.

oxbow_lakes
fonte
11
Sem documentação, qualquer responsável pela chamada assumiria que um método chamado setX define X. Daqui resulta que, se setX realmente define X, sem fazer mais nada importante, então você não precisa de documentação.
Mqp 22/06/2009
Isso é ótimo! Agora, a empresa CrudTech, cuja API eu estou codificando, segue sua convenção ou segue outra pessoa nesse segmento? Hmmmm
oxbow_lakes
5
Não faz sentido escrever "define o preço" no documento setPrice se o método apenas definir o valor da propriedade price, mas se, por exemplo, também atualizar a propriedade totalPrice e recalcular o imposto, esse comportamento deverá obviamente ser documentado.
João Marcus
8
Parece que você está solicitando a documentação para indicar "Isso faz o que você espera". O que é um pouco como escrever "Cuidado: QUENTE" em uma xícara de café. Em um mundo perfeito, não haveria necessidade de dizer essas coisas.
precisa
1
Sim - tendo usado APIs em que métodos chamados coisas como setXtiveram efeitos colaterais diferentes dos esperados, posso afirmar com confiança que este não é um mundo perfeito.
Ox4_lakes
4

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();
TermWay
fonte
2
O problema com essa abordagem é que o Javadoc não gera a documentação privada por padrão! Nesse caso, a tag de referência {@see #salary}é inválida na documentação gerada.
Jarek Przygódzki
1

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 é?

Henrik Paul
fonte
6
E se getFirstName () retornar nulo? Onde isso seria documentado?
22610 Steve Kuo
Que tal security.getFinalMaturity ()? Nem todos os nomes de propriedades têm um significado imediatamente compreensível. Você gostaria de ser demitido por não saber o que isso significa?
22711 Michael Borgwardt
E se o método for implementado por swizzling? Como você deve saber disso, a menos que tenha sido claramente documentado? Como você deve saber que é um criador de padrões, a menos que o documento diga que é?
22420 oxbow_lakes
2
get / set deve, em minha opinião, ser reservado para getters e setters. As pesquisas no banco de dados devem ser nomeadas como "lookupPerson" ou mais.
Thorbjørn Ravn Andersen
1

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.

Thorbjørn Ravn Andersen
fonte
1
Há uma diferença entre comentar e documentar.
Tom Hawtin - tackline,
1
Muito verdadeiro. É exatamente por isso que não comento getters e setters. Eles devem ser auto-explicativos, e adicionar um comentário indica que o código não é auto-explicativo.
Thorbjørn Ravn Andersen
0

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.

akf
fonte
Não é bom - as pessoas não lêem os comentários do campo. Javadoc nem gera a documentação privada por padrão, e os IDEs não mostram a documentação do campo quando você usa ajuda rápida em uma chamada de método.
precisa saber é o seguinte
as pessoas não leem os comentários do campo, a menos que precisem. Quando houver necessidade, quanto mais informações, melhor.
Akf
0

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

Alex B
fonte
0

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

Paul Sonier
fonte
Eles são apenas auto-explicativos se você disser "este é um configurador de propriedades". Caso contrário, um cliente da API não tem idéia do que seja o que está realmente acontecendo dentro dos métodos
oxbow_lakes
1
Quem disse algo sobre auto-explicativo?
22909 Paul Sonier