Commentaires Getter / Setter simples
Quelle convention utilisez-vous pour commenter les getters et 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 exactement 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 le contexte, mais pour la majorité des getters/setters là-bas, le libellé est presque exactement le même.
Je suis juste curieux de savoir si, pour les simples getters/setters, il est normal de ne remplir que la partie (a) OR la partie (b).
Qu'est-ce que tu penses?
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 a pas de duplication.
Absolument inutile - vous êtes mieux sans 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 justifié:
/**
* 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 bean plein de propriétés avec des noms obscurs que seuls les banquiers d'investissement, 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.
Généralement rien, si je peux l'aider. Les getters et les setters devraient 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.
Je dirais ne vous inquiétez de commenter les getters et setters que s'ils ont une sorte d'effet secondaire, ou nécessitent une sorte de condition préalable en dehors de l'initialisation (par exemple: obtenir supprimera un élément d'une structure de données, ou afin de définir quelque chose dont vous avez besoin d'avoir x et y en place en premier). Sinon, les commentaires ici sont assez redondants.
Edit: De plus, si vous trouvez 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 (c'est-à-dire: pousser et sauter pour une pile) [Merci pour les commentaires ci-dessous]
Demandez-vous ce que vous voulez que les gens voient lorsque les commentaires sont affichés en tant que JavaDocs (à partir d'un navigateur). Beaucoup de gens disent que la documentation n'est pas nécessaire car c'est évident. Cela ne sera pas valable 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 dans quel salaire est exprimé. Il s’agit de cents, de dollars, de livres, de 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 documente que la hauteur est en mètres.
Pourquoi ne pas simplement inclure une balise de référence pour vous permettre de commenter la valeur du champ et la référence des getters et 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).
Ce type de passe-partout peut être évité en utilisant Project Lombok . Documentez simplement la variable de champ, même si elle est private, et laissez les annotations Lombok générer des getters et setters correctement documentés.
Pour moi, cet avantage vaut à lui seul coûts .
Je suis vraiment déçu des réponses disant 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 régleur de propriétés JavaBean standard sauf si vous dites si clairement dans la documentation?
Sans documentation, un appelant n'aurait aucune idée si la méthode avait des effets secondaires, si ce n'est en croisant les doigts sur l'apparente convention 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é.
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();
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 se réfère uniquement aux getters et setters. Je crois que tout ce qui n'est pas anodin devrait être correctement javadé.
Commenter les accesseurs, surtout s'ils ne font aucune opération n'importe où, est inutile et un gaspillage du bout des doigts.
Si quelqu'un qui lit votre code ne comprend pas que person.getFirstName() renvoie le prénom d'une personne, vous devriez essayer tout ce qui est en votre pouvoir pour le 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 le documenter.
Si, d'autre part, votre person.getFirstName() ne renvoie pas le prénom d'une personne ... eh bien, n'allons pas là-bas, n'est-ce pas?
il est correct de remplir la partie (b), surtout si vous mettez un commentaire à la déclaration de champ indiquant de quoi parle le champ.
Si le javadoc n'ajoute rien, je le supprime et j'utilise les commentaires générés automatiquement.
Je remplis toujours les deux. Le temps supplémentaire passé à taper est négligeable, et plus d'informations valent mieux que moins, en général.
S'il s'agit d'un getter/setter, il doit être documenté.
Je m'éloigne ici, mais si cela peut devenir une propriété, c'est peut-être mieux pour un codage plus simple des utilisateurs de la classe. Je m'éloigne davantage mais comme pour tous les commentaires qui contiennent "Java" n'importe où, qui a dit que c'était java? (les balises, mais la question pourrait s'appliquer n'importe où vraiment)