Avez-vous l'utilisation de Javadoc pour chaque méthode que vous écrivez?

Question

Devrais-je écrire Doc Commentaires pour l'ensemble de mes méthodes de java?

Answer 1

[VonC: je viens de modifier ma réponse dans un wiki de la communauté dans le but de synthétiser le meilleur de l'autre des réponses et vous permettent de choisir ce un -- communauté de sens, je ne suis pas ici pour le karma: le choix de ce on ne va pas me faire tout rep' points -- le Modifier pour le rendre meilleur]

@Claudiu

Quand j'écris du code que d'autres l'utilisent - Oui. Chaque méthode que quelqu'un d'autre peut utiliser (une méthode publique) doit avoir une javadoc au moins en indiquant son but évident.

@Daniel Spiewak

J'ai bien documenter chaque méthode publique dans chaque classe de l'API. Les Classes qui ont le public et les membres, mais qui ne sont pas destinés à la consommation extérieure sont mises en évidence marquée dans la javadoc de la classe. J'ai aussi une documentation de chaque méthode protégée dans chaque classe de l'API, mais dans une moindre mesure. Cela va à l'idée que n'importe quel développeur qui est l'extension d'une classe de l'API va déjà avoir une juste notion de ce qui se passe.

Enfin, je vais occasionnellement document privé et colis privé méthodes pour mon propre bénéfice. Toute méthode ou un champ qui, je pense, besoin de quelque explication de son utilisation recevront de la documentation, quelle que soit sa visibilité.

@Paul de Vrieze

Pour les choses, comme trivial getters et setters, partager le commentaire de décrire l'objet de la propriété, pas de getter/setter

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

Et oui, c'est plus de travail.

@VonC

Lorsque vous cassez un énorme complexe de la méthode (en raison de la forte complexité cyclomatique raison) sur:

• un seul appel de méthode
• plusieurs méthodes privées qui représentent des escaliers à l'intérieur de la sphère publique

il est très utile de javadoc les méthodes privées ainsi, même si la documentation ne sera pas visible dans la javadoc de l'API de fichiers.
Encore, il vous permet de mémoriser plus facilement la nature précise des différentes étapes de la complexité de votre algorithme.

Et rappelez-vous: les valeurs limites ou les conditions aux limites doivent faire partie de votre javadoc ainsi.

De Plus, javadoc est bien mieux que de simples "//commentaire":

• Il est reconnu par l'IDE et utilisé pour afficher une fenêtre pop-up lorsque vous déplacez votre curseur sur le dessus de l'un de vos - javadoc-ed - fonction. Par exemple, une constante - c'est-private static final variable, doit avoir une javadoc, surtout quand sa valeur n'est pas trivial. Affaire au point: regexp (sa javadoc devrait inclut les regexp dans sa non-échappé à la forme, qu'est-ce que le but est, et un littéral exemple compensée par la regexp)
• Il peut être analysé par des outils externes (comme xdoclet)

@Domci

Pour moi, si quelqu'un va le voir ou pas n'a pas d'importance - il est peu probable que je vais savoir ce que certains obscur morceau de code que j'ai écrit n'est qu'après une couple de mois. [...]
En bref, commentaire de la logique, pas la syntaxe, et de faire qu'une seule fois, sur un endroit approprié.

@Miguel Ping

Afin de commenter quelque chose, vous devez comprendre d'abord. Lorsque vous essayer de commenter une fonction, vous êtes en train de penser de ce que la méthode/fonction/classe n', et cela fait de vous être plus précis et clair dans votre javadoc, qui à son tour vous fait écrire plus de code clair et concis, ce qui est bon.

Answer 2

Si la méthode est bien sûr évident, je pourrait passer un commentaire javadoc.

Des commentaires comme

/ * Ne* Foo */
 void doFoo();

Ne sont pas vraiment utiles. (Trop simpliste exemple, mais vous voyez l'idée)

Answer 3

J'ai soigneusement document chaque méthode publique dans chaque classe de l'API. Les Classes qui ont le public et les membres, mais qui ne sont pas destinés à la consommation extérieure sont mises en évidence marquée dans la javadoc de la classe. J'ai aussi une documentation de chaque méthode protégée dans chaque classe de l'API, mais dans une moindre mesure. Cela va à l'idée que n'importe quel développeur qui est l'extension d'une classe de l'API va déjà avoir une juste notion de ce qui se passe.

Enfin, je vais occasionnellement document privé et colis privé méthodes pour mon propre bénéfice. Toute méthode ou un champ qui, je pense, besoin de quelque explication de son utilisation recevront de la documentation, quelle que soit sa visibilité.

Answer 4

Pour les choses, comme trivial getters et setters, partager le commentaire de décrire l'objet de la propriété, pas de getter/setter.

/** 
 * Get foo
 * @return The value of the foo property
 */
int getFoo() {
  return foo;
}

Est pas utile. Mieux de faire quelque chose comme:

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

Et oui, c'est plus de travail.

Answer 5

Toutes les bases sont couvertes par d'autres, déjà, une remarque supplémentaire:

Si vous vous retrouver à faire ceci:

/**
 * This method currently launches the blaardh into the bleeyrg.
 */
void execute() { ... }

Pensez à changer dans ce:

void launchBlaardhIntoBleeyrg() { ... }

Cela peut sembler évident, mais dans de nombreux cas, la possibilité est facile de manquer dans votre propre code.

Enfin, gardez à l'esprit que le changement n'est pas toujours le voulait; par exemple le comportement de la méthode peuvent être appelés à évoluer au fil du temps (notez que le mot "actuellement" dans la JavaDoc).