Commentaires simples Getter / Setter

125

Quelle convention utilisez-vous pour commenter les getters et les setters? C'est quelque chose que je me demande depuis un certain temps, 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 la même chose pour 1a / b et 2a / b, quelque chose comme 1a) Fixe le salaire de l'employé, 1b) le salaire de l'employé. Cela semble tellement redondant. Maintenant, je pourrais voir quelque chose de plus complexe que vous pourriez écrire plus dans les parties (a), pour donner un contexte, mais pour la majorité des getters / setters, le libellé est presque exactement le même.

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

Qu'est-ce que tu penses?

ThaDon
la source
54
En passant, veuillez ne pas utiliser le flottant pour quoi que ce soit d'argent (comme un salaire ici), jamais. Voir par exemple stackoverflow.com/questions/965831/…
Jonik
3
Utilisez plutôt BigDecimal.
Josep

Réponses:

84

Je remplis généralement 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) sortiront propres et il n'y aura pas de duplication.

sleske
la source
Pouvez-vous corriger la faute de frappe? "@return part for setters"
Jonik
1
Il y a aussi une faute de frappe dans le commentaire de Salaire (). Ce n'est pas un commentaire JavaDoc.
Fostah
1
Je conviens que c'est la meilleure approche pour commenter les accesseurs.
Fostah
31
Ajouter du bruit à votre code dans le but de faire taire les avertissements trop pédants de nos outils me semble mal. Si cela n'ajoute pas de valeur à un programmeur, alors la bonne solution serait de baisser / corriger la verbosité des outils et / ou de réduire à quel point nous nous soucions de sauter à travers les cerceaux pour que les outils nous récompensent. Les outils d'analyse sont censés nous aider et économiser des efforts, pas créer des tâches plus insensées pour nous.
Lyle
1
@Lyle C'est peut-être vrai, mais j'ai l'impression qu'il y a presque toujours quelque chose d'utile qu'un programmeur peut dire qui décrit un getter / setter mieux que la signature de méthode seule. Oui, il y a des cas où un programmeur est paresseux et ne fait que répéter la signature de la méthode dans le commentaire, mais je pense qu'en général, c'est un comportement utile à forcer.
Matt Vukas
174

Absolument inutile - vous êtes mieux sans ce genre de merde qui encombre 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 signifie réellement la propriété peut être cruciale dans les modèles de domaine. Chaque fois que je vois un haricot plein de propriétés aux noms obscurs que seuls les banquiers d'investissement, les biochimistes ou les physiciens quantiques comprennent, et que les commentaires expliquent que la méthode setGobbledygook () "définit le gobbledygook.", Je veux étrangler quelqu'un.

Michael Borgwardt
la source
2
Mes sentiments exactement, les pires sont les modèles spécifiques au domaine où seul un expert du domaine sait ce que signifie la propriété.
ThaDon
7
Même si cela est utile, que feriez-vous pour getFoo (). Copierez-vous également le même commentaire pour getFoo ()?
Vinoth Kumar CM
3
@cmv: Evidemment, la partie "param" ne serait pas copiée. Je ne sais pas si la valeur d'avoir les informations attachées aux deux accesseurs justifie directement la duplication des informations. Probablement oui. Encore mieux serait un moyen de joindre un commentaire aux deux; Je crois que cela est disponible dans Project Lombok.
Michael Borgwardt
@VinothKumar: il serait peut-être plus agréable d'expliquer simplement la propriété dans le getter (comme dans "Foo est le facteur d'ajustement utilisé dans le calcul de la barre.") Et les effets de la modification de la valeur dans le setter (ou si c'est nécessaire ou ne pas initialiser cette valeur - dans l'exemple de la réponse, il n'est pas nécessaire d'initialiser Foo car "il a une valeur par défaut dépendant du type Baz").
freitass
+1 pour "des noms obscurs que seuls les banquiers d'investissement, les biochimistes ou les physiciens quantiques comprennent"
Jackson
36

Généralement rien, si je peux l'aider. Les getters et les 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.

Eric Wendelin
la source
5
Une autre réponse valable dans ce sens pourrait être "les conceptions avec des getters et des setters ne comprennent pas correctement la notion d'encapsulation" :)
Trejkaz
2
@Trejkaz: Ce n'est pas vrai, car les méthodes d'accès autorisent les propriétés en lecture seule ou en écriture seule, ainsi que le polymorphisme (et donc le wrapping, le proxy, etc.).
Laurent Pireyn
2
Ils peuvent permettre ces choses, mais souvent un modèle de constructeur peut remplacer les setters (moins mutables) ou un modèle de visiteur peut remplacer les getters (plus flexible.)
Trejkaz
J'aime certainement et j'utilise le modèle de construction, mais il y a tellement de support pour les POJO (par exemple dans Hibernate) que les getters et les setters ont toujours leur place très importante, pour le meilleur ou pour le pire. C'est la chose la plus épineuse à propos de Java, à mon humble avis, et après avoir écrit des JavaDocs répétitifs pendant plus d'une décennie, je suis sur le point de m'abonner aux conseils de @ sleske.
Michael Scheper
34

Je dirais que ne vous inquiétez que de commenter les getters et les setters s'ils ont une sorte d'effet secondaire ou s'ils nécessitent une sorte de condition préalable en dehors de l'initialisation (c'est-à-dire: obtenir supprimera un élément d'une structure de données, ou afin de définir quelque chose dont vous avez besoin pour avoir x et y en premier). Sinon, les commentaires ici sont assez redondants.

Edit: De plus, si vous constatez que beaucoup d'effets secondaires sont impliqués dans votre getter / setter, vous voudrez peut-être changer le getter / setter pour avoir un nom de méthode différent (par exemple: pousser et pop pour une pile) [Merci pour les commentaires ci-dessous]

Gopherkhan
la source
10
sans doute, vous devriez changer le nom des getters qui ont des effets secondaires pour être plus clair, car tous les développeurs ne liront pas les commentaires.
akf
C'est bien - mais cela oblige les utilisateurs de votre API à savoir que s'il y avait eu des effets secondaires, ils auraient été documentés !
oxbow_lakes
akf, je pensais exactement cela après avoir posté :) Je suppose que je vais l'ajouter à ma réponse.
Gopherkhan
1
mais si vous ne documentez pas les getters et les setters "stupides" (c'est ce que je préfère aussi!) - comment vous débarrasser des avertissements Eclipse sur javadoc manquant? Je ne veux pas encombrer mon espace de travail avec des avertissements de ce genre, mais je ne veux pas non plus que cet avertissement soit désactivé pour toutes les autres méthodes ...
Zordid
12

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 évident. Cela ne tiendra pas si le champ est privé (sauf si vous activez explicitement JavaDocs pour les champs privés).

Dans ton cas:

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

On ne sait pas en quoi le salaire est exprimé. C'est des cents, des dollars, des livres, du 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.

Steve Kuo
la source
1
bien que je sois d'accord avec vous, je pense qu'il faut s'assurer que les commentaires de fonction ne sont pas un nom de fonction mal choisi et non explicite.
karlipoppins
Je suis un grand partisan de JavaDocs, mais aussi un grand partisan du code auto-documenté. Donc pour le passeur au moins, je ferais quelque chose commepublic void setSalary(float aud) (ou plus réaliste, public void setSalary(BigDecimal aud)). Mieux encore, la propriété doit être de type abstract class CurrencyAmount, qui à son tour a les propriétés java.util.Currency currencyet java.math.BigDecimal amount. La plupart des développeurs avec lesquels j'ai travaillé sont terriblement paresseux avec JavaDoc, mais appliquer une API comme celle-ci rend cela moins problématique.
Michael Scheper
Si l'unité est une unité SI comme les mètres / secondes, il est moins nécessaire de documenter, si ce n'est pas une unité Si, elle doit être documentée ou mieux nommée pour inclure l'unité non standard, par exemple heightFeet
AlexWien
8

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 les javadocs privés sont activés, c'est le cas).

Steve
la source
Je suis d'accord. Et puis j'ai réalisé, pourquoi écrire tout ce passe-partout de toute façon? Voir ma réponse sur le projet Lombok.
Michael Scheper
7

Ce type de passe-partout peut être évité en utilisant le projet Lombok . Documentez simplement la variable de champ, même si elleprivate , et laissez les annotations Lombok générer des getters et des setters correctement documentés.

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

Michael Scheper
la source
4

Je suis vraiment déçu des réponses qui disent essentiellement qu'une 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 setXest un setter 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, autre que de croiser les doigts sur 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 setXfait beaucoup plus que simplement définir une propriété.

oxbow_lakes
la source
11
Sans documentation, tout appelant supposerait qu'une méthode appelée setX définit X. Il s'ensuit que si setX définit réellement X, sans rien faire d'autre d'important, alors vous n'avez pas besoin de documentation.
mqp
C'est génial! Maintenant, cette société CrudTech, dont je codifie l'API, suit-elle votre convention ou suit-elle celle de quelqu'un d'autre sur ce fil? Hmmmm
oxbow_lakes
5
Il ne sert à rien d'écrire "définit le prix" dans le document setPrice si la méthode définit simplement la valeur de la propriété price, mais si elle met également par exemple à jour la propriété totalPrice et recalcule la taxe, un tel comportement doit évidemment être documenté.
João Marcus
8
Vous semblez demander que la documentation indique «Cela fait ce que vous attendez». Ce qui est un peu comme écrire "Attention: HOT" sur une tasse de café. Dans un monde parfait, il ne serait jamais nécessaire de dire de telles choses.
Kevin Panko
1
Oui - ayant utilisé des API où des méthodes appelées des choses comme setXavaient des effets secondaires autres que ceux attendus, je peux en effet affirmer avec confiance que ce n'est pas un monde parfait.
oxbow_lakes
4

S'il n'y a pas d'opération spéciale dans 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 option d'extrait privé):

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

/** @return #salary. */
public float salary();
TermWay
la source
2
Le problème avec cette approche est que Javadoc ne génère pas la documentation privée par défaut! Dans ce cas, la balise de référence {@see #salary}n'est pas valide dans la documentation générée.
Jarek Przygódzki
1

Commenter les accesseurs, surtout s'ils n'effectuent aucune opération nulle part, est inutile et un gaspillage du bout des doigts.

Si quelqu'un qui lit votre code ne peut pas comprendre que person.getFirstName()renvoie le prénom d'une personne, vous devriez essayer tout ce qui est en votre pouvoir pour la faire virer. S'il fait de la magie dans la base de données, lance quelques dés, appelle le secrétaire aux prénoms pour obtenir le prénom, il est prudent de supposer que c'est une opération non triviale et de bien la documenter.

Si, par contre, vous person.getFirstName()ne retournez pas le prénom d'une personne ... eh bien, n'y allons pas, d'accord?

Henrik Paul
la source
6
Que faire si getFirstName () renvoie null? Où cela serait-il documenté?
Steve Kuo
Qu'en est-il de security.getFinalMaturity ()? Tous les noms de propriétés n'ont pas une signification immédiatement compréhensible. Voudriez-vous être congédié pour ne pas savoir ce que cela signifie?
Michael Borgwardt
Et si la méthode est implémentée par swizzling? Comment êtes-vous censé savoir cela à moins que cela ne soit clairement documenté? Comment êtes-vous censé savoir que c'est un normalisateur à moins que le doc ne le dise?
oxbow_lakes
2
get / set devrait à mon avis être réservé aux getters et aux setters. Les recherches dans la base de données doivent être nommées "lookupPerson" ou ainsi.
Thorbjørn Ravn Andersen
1

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

En règle générale, 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 getters et les setters. Je crois que tout ce qui n'est pas trivial devrait être correctement javadoré.

Thorbjørn Ravn Andersen
la source
1
Il y a une différence entre commenter et documenter.
Tom Hawtin - tackline
1
Très vrai. C'est pourquoi je ne commente pas les getters et les setters. Ils doivent être explicites, et l'ajout d'un commentaire indique que le code n'est pas explicite.
Thorbjørn Ravn Andersen
0

il est correct de remplir la partie (b), surtout si vous mettez un commentaire à la déclaration de champ indiquant de quoi il s'agit.

akf
la source
Pas bon - les gens ne lisent pas les commentaires sur le terrain. Javadoc ne génère même pas la documentation privée par défaut, et les IDE ne vous montrent pas la documentation de terrain lorsque vous utilisez l'aide rapide sur un appel de méthode.
Trejkaz
les gens ne lisent pas les commentaires sur le terrain sauf s'ils en ont besoin. Une fois qu'il y a un besoin, plus il y a d'informations, mieux c'est.
akf
0

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

Alex B
la source
0

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

Paul Sonier
la source
Ils ne sont explicites que si vous dites "ceci est un poseur de propriété". Sinon, un client de l'API n'a aucune idée de ce qui se passe réellement dans les méthodes
oxbow_lakes
1
Qui a dit quoi que ce soit sur explicite?
Paul Sonier