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?
Réponses:
Je remplis généralement la partie param pour les setters et la partie @return pour les getters:
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.
la source
Absolument inutile - vous êtes mieux sans ce genre de merde qui encombre votre code:
Très utile, si nécessaire:
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.
la source
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.
la source
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]
la source
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:
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:
La première ligne indique qu'elle renvoie la hauteur. Le paramètre de retour indique que la hauteur est en mètres.
la source
public void setSalary(float aud)
(ou plus réaliste,public void setSalary(BigDecimal aud)
). Mieux encore, la propriété doit être de typeabstract class CurrencyAmount
, qui à son tour a les propriétésjava.util.Currency currency
etjava.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.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.
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).
la source
Ce type de passe-partout peut être évité en utilisant le projet Lombok . Documentez simplement la variable de champ, même si elle
private
, 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 .
la source
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
setX
est 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
setX
fait beaucoup plus que simplement définir une propriété.la source
setX
avaient des effets secondaires autres que ceux attendus, je peux en effet affirmer avec confiance que ce n'est pas un monde parfait.S'il n'y a pas d'opération spéciale dans getter / setter, j'écris habituellement:
Avec Javadoc (avec option privée):
et / ou
Avec Doxygen (avec option d'extrait privé):
la source
{@see #salary}
n'est pas valide dans la documentation générée.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?la source
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é.
la source
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.
la source
Si le javadoc n'ajoute rien, je supprime le javadoc et utilise les commentaires générés automatiquement.
la source
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.
la source