Commentaires Getter / Setter simples

Question

Quelle convention utilisez-vous pour commenter les getters et les setters? C’est quelque chose que je me suis demandé depuis longtemps, par exemple:

/**
 * (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();

Je trouve toujours que j'écris à peu près exactement la même chose pour 1a / b et 2a / b, quelque chose comme 1a) définit le salaire de l'employé, 1b) le salaire de l'employé. Cela semble tellement superflu. Maintenant, je pourrais voir quelque chose de plus complexe, vous pourriez écrire plus dans les parties (a), pour donner un contexte, mais pour la majorité des getters / setters, le libellé est presque identique.

Je suis juste curieux de savoir si, pour les simples getters / setters, il est autorisé à ne remplir que la partie (a) OU la partie (b).

Qu'en pensez-vous?

Answer 1

Habituellement, je ne remplis que la partie param pour les setters et la partie @return pour les 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();

De cette façon, les outils de vérification javadoc (tels que les avertissements d’Eclipse) n’auront pas à être dupliqués.

Answer 2

Absolument inutile - vous feriez mieux de ne pas avoir ce genre de merde encombrant votre code:

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

Très utile, si nécessaire:

/**
 * 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);

En particulier, l'explication de ce que la propriété signifie réellement peut être cruciale dans les modèles de domaine. Chaque fois que je vois un grain plein de propriétés aux noms obscurs que seuls les banquiers, les biochimistes ou les physiciens quantiques comprennent, et les commentaires expliquent que la méthode setGobbledygook () "définit le gobbledygook", je veux étrangler quelqu'un.

Answer 3

En règle générale rien, si je peux aider. Getters et setters doivent s'expliquer d'eux-mêmes.

Je sais que cela ressemble à une non-réponse, mais j'essaie d'utiliser mon temps pour commenter des choses qui nécessitent des explications.

Answer 4

Je dirais uniquement que vous souhaitez commenter les accesseurs et les setters s’ils ont un effet secondaire ou une condition préalable en dehors de l’initialisation (par exemple, le fait de récupérer un élément d’une structure de données, ou pour définir vous devez avoir en premier lieu x et y). Sinon, les commentaires ici sont plutôt redondants.

Éditer: En outre, si votre getter / setter implique de nombreux effets secondaires, vous voudrez peut-être changer le getter / setter pour lui attribuer un nom de méthode différent (par exemple: push et pop pour une pile) [Merci pour les commentaires ci-dessous]

Answer 5

Demandez-vous ce que vous voulez que les gens voient lorsque les commentaires sont affichés sous forme de JavaDocs (à partir d'un navigateur). Beaucoup de gens disent que la documentation n'est pas nécessaire car c'est une évidence. Cela ne tiendra pas si le champ est privé (sauf si vous activez explicitement JavaDocs pour les champs privés).

Dans votre cas:

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

Le salaire exprimé n’est pas clair. Il s’agit de cents, dollars, livres sterling, RMB?

Lors de la documentation des setters / getters, j'aime séparer le quoi de l'encodage. Exemple:

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

La première ligne indique qu’elle renvoie la hauteur. Le paramètre de retour indique que la hauteur est en mètres.

Answer 6

Pourquoi n'incluent-ils pas simplement une balise de référence pour vous permettre de commenter la valeur du champ et la référence des getters et des setters.

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

public String getFoo() {
  return foo;
}

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

Pour que la documentation s’applique au getter et au setter ainsi qu’au champ (si javadocs privés est activé, c’est bien le cas).

Answer 7

Ce type de comportement peut être évité en utilisant le Projet Lombok . Il suffit de documenter la variable de champ, même s’il s’agit de private , et de laisser les annotations de Lombok générer des getters et des setters correctement documentés.

Pour moi, cet avantage à lui seul vaut les coûts .

Answer 8

Je suis vraiment déçu des réponses, affirmant en substance que la documentation complète est une perte de temps. Comment les clients de votre API sont-ils censés savoir qu'une méthode appelée setX est un configurateur de propriétés JavaBean standard , à moins que vous ne le disiez clairement dans la documentation ?

Sans documentation, un appelant n'aurait aucune idée si la méthode avait des effets secondaires, sinon en se croisant les doigts au sujet de la convention apparente suivie.

Je suis sûr que je ne suis pas le seul ici à avoir eu le malheur de découvrir à la dure qu’une méthode appelée setX fait bien plus que simplement définir une propriété.

Answer 9

S'il n'y a pas d'opération spéciale dans le getter / setter, j'écris habituellement:

Avec Javadoc (avec option privée):

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

et / ou

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

Avec Doxygen (avec l'option d'extrait privé):

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

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

Answer 10

Il est inutile de commenter les accesseurs, en particulier s’ils n’effectuent aucune opération nulle part.

Si quelqu'un qui lit votre code ne comprend pas que person.getFirstName () renvoie le prénom d'une personne, vous devez tout mettre en oeuvre pour le faire renvoyer. Si cela permet une certaine magie dans la base de données, lance quelques dés, appelle la secrétaire aux prénoms pour obtenir le prénom. Il est prudent de supposer qu’il s’agit d’une opération non triviale et la documenter correctement.

Si, par contre, votre personne.getFirstName () ne renvoie pas le prénom d'une personne ... eh bien, n'allons pas y aller, allons-nous?

Answer 11

Ne rien mettre si le nom du champ est suffisamment descriptif du contenu.

En général, laissez le code être autonome et évitez de commenter si possible. Cela peut nécessiter une refactorisation.

EDIT: Ce qui précède ne concerne que les accesseurs et les setters. Je crois que tout ce qui n'est pas trivial doit être correctement javadoc.

Answer 12

il est correct de remplir la partie (b), surtout si vous mettez un commentaire dans la déclaration du champ indiquant ce que le champ est vraiment.

Answer 13

Si le javadoc n'ajoute rien, je le supprime et utilise les commentaires générés automatiquement.

Answer 14

Je remplis toujours les deux. Le temps supplémentaire passé à taper est dactylographié, et plus d’informations vaut mieux que moins, en général.

Answer 15

S'il s'agit d'un getter / setter, cela doit être documenté.

Je m'éloigne du sujet ici, mais s'il est possible d'en faire une propriété, c'est peut-être mieux pour un codage plus simple des utilisateurs de la classe. Je m'éloigne un peu plus loin mais pour tous les commentaires qui ont " java " n'importe où en eux, qui a dit que c'était java? (les balises, mais la question pourrait s'appliquer vraiment n'importe où)