Commentaires simples de Getter / Setter

Quelle convention utilisez-vous pour commenter les getters et les formateurs? C’est quelque chose que je me suis demandé pendant 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 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 juste tellement redondant. Maintenant, je pourrais voir pour 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 identique.

Je suis juste curieux de savoir si, pour les simples importateurs, il est possible de ne remplir que la partie (a) ou la partie (b).

Qu’est-ce que tu penses?

Je remplis généralement la partie param pour les seters 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 de javadoc (tels que les avertissements d’Eclipse) seront propres et il n’y aura pas de duplication.

Absolument inutile – vous feriez mieux de ne pas encombrer votre code avec ce genre de conneries:

 /** * 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 haricot plein de propriétés avec des 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.

Généralement rien si je peux l’aider. Les Getters et les Setters doivent s’expliquer eux-mêmes.

Je sais que cela semble être une non-réponse, mais j’essaie d’utiliser mon temps pour commenter des choses qui nécessitent une explication.

Je dirais que je ne crains pas de commenter les getters et les setters s’ils ont une sorte d’effet secondaire, ou ont besoin d’une sorte de condition préalable en dehors de l’initialisation (par exemple, get enlèverait un élément d’une structure de données ou avoir x et y en place en premier). Sinon, les commentaires ici sont plutôt redondants.

Edit: De plus, si vous trouvez que beaucoup d’effets secondaires sont impliqués dans votre getter / setter, vous pouvez changer le getter / setter pour avoir un nom de méthode différent (ex: push et pop pour une stack) [Merci pour les commentaires ci-dessous]

Demandez-vous ce que vous voulez que les gens voient lorsque les commentaires sont considérés comme JavaDocs (à partir d’un navigateur). Beaucoup de gens disent que la documentation n’est pas nécessaire car elle est évidente. 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 clairement dans quel salaire il est exprimé. Il s’agit de cents, de dollars, de livres, de RMB?

Lorsque je documente les seters / getters, j’aime bien séparer le quoi du codage. 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.

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 des setters.

 /** * The adjustment factor for the bar calculation. * @HasGetter * @HasSetter */ private Ssortingng foo; public Ssortingng getFoo() { return foo; } public void setFoo() { this foo = foo; } 

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

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

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

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 extrait privé):

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

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 setter de propriétés JavaBean standard, à moins que vous ne le disiez clairement dans la documentation ?

Sans documentation, un interlocuteur n’aurait aucune idée que la méthode ait des effets secondaires, sinon en croisant les doigts sur la convention apparente suivie.

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

Il est inutile de commenter les accesseurs, surtout s’ils ne font aucune opération, ce qui est une perte de temps.

Si quelqu’un qui lit votre code ne comprend pas que person.getFirstName() renvoie le prénom d’une personne, vous devriez tout essayer pour le faire virer. S’il fait de la magie avec une firebase database, lance quelques dés, appelle le secrétaire des prénoms pour obtenir le prénom, il est sûr de supposer que c’est une opération non sortingviale et bien la documenter.

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

il est acceptable de remplir la partie (b), surtout si vous placez un commentaire sur la déclaration de champ indiquant le contenu du champ.

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

Je remplis toujours les deux. Le temps supplémentaire passé à la dactylographie est négligeable, et plus d’informations sont meilleures que moins, en général.

Si c’est un getter / setter, il doit être documenté.

Je m’écarte ici, mais si on peut en faire 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 ont “java” n’importe où, qui a dit que c’était java? (les balises, mais la question pourrait s’appliquer n’importe où vraiment)

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 anodin devrait être correctement javadé.