Simples observations de Getter/Setter

Question

Ce que la convention utilisez-vous pour commenter getters et setters? C'est quelque chose que j'ai 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();

J'ai toujours trouve que je suis assez bien écrit 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é. Il semble donc redondant. Maintenant, je pouvais voir quelque chose de plus complexe, vous pouvez écrire plus dans le (a) les parties, pour donner le contexte, mais pour une majorité des getters/setters là le libellé est presque exactement le même.

Je suis juste curieux de savoir si, pour la simple getters/setters son ok à remplir uniquement dans le (partie a) OU (b) de la partie.

Qu'en pensez-vous?

Answer 1

Absolument inutile - que vous êtes mieux sans ce genre de merde qui encombrent votre code:

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

Très utile, si la situation le justifie:

/**
 * 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, en fait, peut être cruciale dans le domaine des modèles. Chaque fois que je vois un haricot complète de propriétés avec d'obscurs des noms qui ne banquiers d'investissement, les biochimistes ou de la physique quantique à comprendre, et les commentaires expliquent que le setGobbledygook() la méthode "définit le charabia.", J'ai envie d'étrangler quelqu'un.

Answer 2

J’ai généralement il suffit de remplir le param pour poseurs et la partie @return pour les acquéreurs :

Cette façon javadoc vérification des outils (tels que les avertissements de l’Eclipse) sortira en propre, et il n’y a pas de chevauchement.

Answer 3

Généralement rien, si je peux l’aider. Getters et setters devraient être suffisamment explicite.

Je sais que sonne comme une non-réponse, mais j’essaie d’utiliser mon temps pour commenter des choses qui ont besoin d’explication.

Answer 4

Je dirais seulement s'inquiéter de commenter les accesseurs et mutateurs si ils ont une sorte d'effet secondaire, ou d'exiger une sorte de condition préalable à l'extérieur de l'initialisation (c'est à dire: se permet de supprimer un élément à partir d'une structure de données, ou dans le but de créer quelque chose, vous devez avoir x et y, en premier lieu). Sinon les commentaires ici sont assez redondante.

Edit: En plus, si vous trouvez un lot d'effets secondaires sont impliqués dans votre getter/setter, vous souhaiterez peut-être modifier les getter/setter pour avoir un autre nom de la méthode (c'est à dire: push et pop pour une pile) [Merci pour les commentaires ci-dessous]

Answer 5

Demandez-vous ce que vous voulez les gens à voir les commentaires sont considérées comme Javadoc (à partir d'un navigateur). Beaucoup de gens disent que la documentation n'est pas nécessaire puisque c'est évident. Ce ne tiendra pas si le terrain est privé (sauf si vous avez explicitement tour sur la documentation Javadoc pour les champs privés).

Dans votre cas:

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

Il n'est pas clair ce que le salaire est exprimé en. Il est cents, dollars, livres, RMB?

Lors de la fixation des setters/getters, je tiens à séparer les ce qui de l'encodage. Exemple:

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

La première ligne indique qu'il retourne la hauteur. Le paramètre de retour des documents que la hauteur est en mètres.