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

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

  • Je crois que le courant de choisir la réponse est incomplète et partiellement faux. J'ai synthétisé le meilleur de l'autre des réponses dans une communauté wiki post (pas de karma impliqués). Vous pourriez envisager de choisir cette place
InformationsquelleAutor mawaldne | 2008-10-17
  1. 52

    @Claudiu

    Lorsque 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

    De 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 haute complexité cyclomatique raison) dans:

    • l'un public, l'appel de méthode
    • plusieurs méthodes privées qui représentent des mesures internes du public est l'un

    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 n'oubliez pas: des valeurs limites ou des conditions aux limites devrait faire partie de votre javadoc ainsi.

    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, un constante - qui 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.

    • formulaire de Maintenant, je vais !
    InformationsquelleAutor
  2. 28

    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)

    • Des accesseurs et des mutateurs sont un autre bon exemple de ce principe.
    • Des accesseurs et des mutateurs peut-être besoin de tels commentaires / * * * * les Utilisateurs prénom. Ne contient pas de symboles autres que a-z,A-z et n'est pas plus de 50 caractères*/ String getFirstName(); /** les Ensembles de prix. Devrait être positif, de précision est réduite à 4 chiffres après le point décimal**/ void setPrice(double prix);
    InformationsquelleAutor tunaranch
  3. 25

    Je fond 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é.

    • "Je vais occasionnellement document privé et colis privé méthodes pour mon propre avantage". C'est très bien si vous êtes la seule personne qui ne va jamais à regarder le code, mais pas autrement.
    • Je ne pense pas que cela répond à la question. Elle ne décrit que ce que vous faites normalement. Je voudrais savoir pourquoi.
    • "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." <-- Comment voulez-vous marquer?
    • Je dirais que la documentation de chaque méthode unique pour le bien de rigueur est une mauvaise idée. Elle conduit à encombré, la mauvaise qualité de la documentation. Code doivent être autonomes, de décrire autant que possible. Mettre des docs sur que c'est une perte de temps pour vous et le lecteur. L'augmentation du niveau de bruit qui rend difficile de voir les docs qui sont réellement importants. Le volume de bêtises docs augmente les chances de docs en train de devenir obsolète, sans être mis à jour. "setName() Définit le nom. \@param name Le nom de l'ensemble". "getName() Récupère le nom. \@return Le nom."
    • Exactement comme NateS dit. Propriété accesseurs (getters et setters) n'ayant aucun comportement/effets secondaires ne doit pas être l'objectif principal de la documentation. Ne pas jamais écrire bruyant répétitif non-sens docs pour les méthodes triviales.
    • Dans une classe, il est souvent difficile de ce nom, parce qu'il est surchargé terme. Il pourrait être un réel nom de la personne, un utilisateur nom d'affichage convivial, il pourrait être quelque chose qui n'est pas destiné à être affiché à un utilisateur, il pourrait être quelque chose qui est utilisé comme une clé dans quelque chose d'autre (comme dans les DOM est window.name qui peut être utilisé comme une cible de liens). Ainsi, alors que je suis d'accord que "Obtient le nom" est un mauvais commentaire qui ne fait rien mais répéter le code, vous avez parfois besoin d'expliquer ce genre de nom est-il.
    • D'accord. Si les docs ne fournissent des informations que le nom de la classe ou de la signature de la méthode fournit, ceux docs ne doit pas être écrit. Ce serait bien: "getName() \@return Le nom et prénom du client, ou la valeur null." Complète les phrases ne sont pas nécessaires. J'utilise le \@return pour les getters si j'ai déjà besoin de commenter la valeur de retour. Dans ce cas, il peut être null. Il serait juste d'expliquer ce que la valeur null signifie, si ce n'est pas évident. Une de mes règles est que les paramètres et valeurs de retour sont supposés non nuls et ceux qui peuvent être null doivent être documentées.
    • Pourquoi ne serait-il pas fine du document privé et le paquet de méthodes privées?

    InformationsquelleAutor Daniel Spiewak
  4. 14

    De 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.

    • À droite sur la! À condition que bla est public. Vous ne voulez pas référence à interne algos dans votre public javadoc.
    • L'utilisateur doit savoir au sujet de bla, afin de définir des foo de façon significative. De ce point de bla est public, même si l'utilisateur ne peut pas modifier les autres données qui y sont associées.
    InformationsquelleAutor Paul de Vrieze
  5. 11

    Toutes les bases couverts 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() { ... }

    Envisager de 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 voulu; 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).

    InformationsquelleAutor volley
  6. 8

    Non, ne faites pas de commentaires de chaque méthode, une variable de classe, etc..

    Voici une citation de "Code Propre: Un Manuel de Logiciel Agile de l'Artisanat":

    Il est tout simplement ridicule d'avoir une règle qui dit que chaque fonction doit avoir une
    javadoc, ou chaque variable doit avoir un commentaire. Les commentaires de ce genre juste le désordre
    le code, popagate mensonges, et de prêter à confusion générale et la désorganisation.

    Un commentaire doit exister si, et seulement si, il ajoute des informations importantes pour la prévu de l'utilisateur de la méthode, variable, classe, etc.. Ce qui constitue un "important" est digne d'intérêt et pourrait être un rappel à moi-même quand/si je reviens à cette méthode/classe/etc., une conséquence ou un effet indésirable de la méthode, de la motivation pour le pourquoi de la chose même qu'il existe (dans le cas où un code est de surmonter une lacune/bug d'une bibliothèque ou d'un système), des informations importantes concernant les performances ou quand il est approprié d'appel, etc..

    Qu'est-ce que pas un bon commentaire, mais indique le code lui-même doit être réécrit/modifié est un commentaire expliquant les détails d'un complexe et obscur de la méthode ou de la fonction. Au lieu de cela, préfère le court le code plus clair.

    InformationsquelleAutor Jason
  7. 6

    Il y a une autre raison pour laquelle vous devez utiliser la documentation javadoc. Afin de commenter quelque chose, vous devez comprendre d'abord. Lorsque vous essayer de commenter une fonction, vous êtes en fait pensée 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.

    InformationsquelleAutor Miguel Ping
  8. 5

    Quand j'écris un code pour moi - même - N. Dans ce cas, java doccing est un gaspillage de mon temps.

    Lorsque j'écris du code que d'autres l'utilisent - Oui. Chaque méthode que quelqu'un d'autre peut utiliser (une méthode publique) devrait avoir un java doc, au moins, en indiquant son but évident. Pour une bonne exécution de test la javadoc de l'utilitaire de création de votre code (j'ai oublié la ligne de commande exacte maintenant). Parcourir par le biais de la page web, il génère. Si vous voulez être satisfaits à l'aide d'une bibliothèque avec un niveau de la documentation, vous êtes d'or. Si non, Écrire plus de la documentation javadoc dans votre code.

    • Je suis en désaccord, je trouve que les commentaires souvent me faire gagner du temps et de l'effort quand je reviens à un projet de 6 mois plus tard.
    • J'ai tellement en désaccord avec la première partie de cette réponse! Et je fais tout à fait d'accord avec nemo commentaire
    • Je viens de proposer à l'auteur de la question pas choisissez votre réponse et choisissez de ma communauté "wiki" (pas de rep' points) résumé de la réponse à la place. Si cela se produit, laissez-moi savoir: je vais upvote deux de vos autres réponses que je trouve intéressant 😉 -15 + 20, vous ne perdrez pas de points!
    • nemo et VonC -- il n'a pas dit qu'il n'a pas de code de document pour lui-même, qu'il n'a pas javadoc il. C'est le genre de ce que je fais.
    • j'ai vraiment écrire des commentaires. il est incroyablement utile. cependant, je trouve la javadoc de style trop lourd, conduisant à de trop de vert entre mon code, ce qui rend difficile à lire. donc javadoccing je pars pour le code d'autres l'utilisent. pour moi, simplement en // les commentaires ne va!
    • Je suis toujours en désaccord. Javadoc est un vieux lourdes format, je vous le concède. Mais il est reconnu par l'IDE et de permettre que la documentation de pop-up lorsque vous utilisez l'un de votre propre fonction ailleurs dans votre code. simple "//commentaire" est pas une bonne solution.

    InformationsquelleAutor Claudiu
  9. 2

    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. Il ya quelques lignes directrices:

    1. Api, les classes du framework, interne et réutilisables méthodes statiques doit être commentée à fond.

    2. Logique dans chaque pièce compliquée du code doit être expliqué sur deux lieux général de la logique dans la javadoc, et de la logique pour chaque partie significative de code dans son propre commentaire.

    3. Propriétés du modèle doit être commentée si elles ne sont pas évidentes. Par exemple, aucun point en commentant nom d'utilisateur et le mot de passe, mais le type a au moins un commentaire qui dit quelles sont les valeurs possibles pour le type.

    4. Je n'ai pas de document getters, setters, ou tout ce qui est fait "par le livre". Si l'équipe a un niveau moyen de créer des formulaires, des adaptateurs, des contrôleurs, des façades... je n'ai pas le document, car il n'y a pas de point si toutes les cartes sont les mêmes et ont un ensemble de méthodes standard. Quiconque est familier avec cadre permettra de savoir ce qu'ils pour - en supposant que le cadre de la philosophie et de la façon de travailler avec, il est documenté quelque part. Dans ce cas, les commentaires moyenne supplémentaire de l'encombrement et n'ont aucun but. Il y a des exceptions à cela quand la classe n'quelque chose de non-standard - puis court commentaire est utile. Aussi, même si je suis en création de formulaire dans un façon standard, j'aime diviser les pièces de la forme de courts commentaires de diviser le code en plusieurs parties, par exemple "adresse de facturation commence ici".

    En bref, commentaire de la logique, pas la syntaxe, et de faire qu'une seule fois, sur un endroit approprié.

    • Votre réponse a quelque chose de bon en elle, à mon avis. +1. Et j'ai référencé dans ma "communauté-wiki-" résumé de la réponse
    InformationsquelleAutor Domchi
  10. 2

    Java doc ne doit pas être invoqué, car il place un fardeau sur les développeurs à faire des changements pour maintenir la java doc ainsi que le code.

    Classe noms et les noms de fonction devrait être assez explicite pour expliquer ce qui se passe.

    Si pour expliquer ce qu'est une classe ou d'une méthode ne rend son nom trop long à traiter avec, la classe ou la méthode n'est pas assez concentré, et devrait être remaniée en unités plus petites.

    • La charge aux développeurs d'expliquer ce que leurs méthodes ne. Les noms de méthode doit être court, si possible, et cela peut les empêcher d'être auto-explicatif, surtout si il y a de nombreux paramètres et/ou de la méthode des effets secondaires. En outre, l'objet retourné peut ne pas être évident dans certains cas.
    InformationsquelleAutor Kieth Smith
  11. 1

    il suffit de mettre: OUI

    Temps, vous avez besoin de réfléchir pour savoir si vous devez écrire une doc,
    est mieux investi dans l'écriture d'un doc.

    L'écriture d'un one-liner est mieux que de perdre du temps pour ne pas documenter la méthode du tout à la fin.

    InformationsquelleAutor Marcus Tik
  12. 1

    J'ai le sentiment qu'il devrait au moins être des commentaires concernant les paramètres acceptés et les types de retour en terme de ce qu'ils sont.

    On peut ignorer les détails de mise en œuvre dans le cas où les noms de fonction décrit complètement, par exemple, sendEmail(..);

    InformationsquelleAutor Nrj
  13. 1

    Vous devriez probablement être la description de vos méthodes vraiment. Le plus important ce sont les API de méthodes (en particulier publiée méthodes de l'API). Les méthodes privées sont parfois pas documentée, même si je pense qu'ils devraient être, pour plus de clarté - en va de même avec les méthodes protected. Vos commentaires doivent être instructif, et pas seulement réitérer ce que fait le code.

    Si une méthode est particulièrement complexe, il vous est conseillé de le documenter. Certaines personnes croient que le code doit être écrit clairement de sorte qu'il ne nécessite pas de commentaires. Cependant, ce n'est pas toujours possible, donc les commentaires doivent être utilisés dans ces cas.

    Vous pouvez automatiser la génération de la Javadoc des commentaires pour les getters/setters de Eclipse via le code des modèles pour enregistrer la quantité de documents que vous avez à écrire. une autre astuce est d'utiliser le @{$inheritDoc} pour éviter la duplication de code les commentaires entre les interfaces et les classes d'implémentation.

    InformationsquelleAutor Jon
  14. 1

    Javadoc peut être vraiment utile pour les bibliothèques et les composants réutilisables. Mais soyons plus pratique. Il est plus important d'avoir l'auto expliquant que le code de javadoc.
    Si vous imaginez un énorme héritage de projet avec la documentation Javadoc, que ferais - tu l'invoquer? Je ne le crois pas... Quelqu'un a ajouté Javadoc, puis la mise en œuvre a changé, la nouvelle fonctionnalité a été ajoutée (supprimé), de sorte que la Javadoc ai obsolètes.
    Comme je l'ai dit j'aime bien avoir de la documentation javadoc pour les bibliothèques, mais pour les projets actifs, je préfère

    • de petites fonctions/classes avec des noms qui décrivent ce qu'ils font
    • claire de l'unité des cas de test qui donne une explication de ce que le
      fonction/classes ne
    InformationsquelleAutor HamoriZ
  15. 0

    à une société précédente, nous avons utilisé la bagnole formateur de code avec eclipse. Qui ajoutent de la javadoc pour toutes les méthodes, y compris privés.

    Il a rendu la vie difficile à documenter les setters et getters. Mais ce que le diable. Vous avez à faire -- vous le faites. Qui m'a fait apprendre quelques fonctionnalités de macro avec XEmacs 🙂 Vous pouvez automatiser encore plus loin en écrivant un java analyseur et intervenant comme ANTLR créateur a fait il y a plusieurs années 🙂

    actuellement, j'document, toutes les méthodes publiques et quelque chose de plus de 10 lignes.

    • Je pense qu'il parle en fait de la création de la documentation de commentaires et pas simplement mettre en inutile @param foo des trucs sans substance (qui est pire que pas de javadoc à tous)
    InformationsquelleAutor anjanb
  16. 0

    Je me fais un point d'écrire des commentaires javadoc chaque fois qu'il est non-trivial, l'Écriture de commentaires javadoc lors de l'utilisation d'un IDE comme eclipse ou netbeans n'est pas gênant. En outre, lorsque vous écrivez un commentaire javadoc, vous êtes obligé de penser non seulement ce que la méthode n', mais que la méthode ne exactement, et les hypothèses que vous avez faites.

    Une autre raison est que une fois que vous avez compris votre code et refactorisé, la javadoc permet d'oublier ce qu'il fait, puisque vous pouvez toujours vous référer à elle. Je ne dis pas exprès d'oublier ce que vos méthodes mais c'est juste que je préfère rappeler d'autres choses qui sont plus importantes.

    InformationsquelleAutor blizpasta
  17. 0

    Vous pouvez exécuter javadoc contre le code qui n'a pas de commentaires javadoc et il va produire assez utilisable javadocs si vous donnez réfléchie des noms à vos méthodes et des paramètres.

    InformationsquelleAutor Paul Croarkin
  18. 0

    J'essaie au moins de documenter tous les publics et à l'interface de la propriété et de la méthode, de sorte que des gens en les appelant dans mon code savoir ce que les choses sont. J'essaye aussi d'expliquer autant que possible en ligne ainsi que pour l'entretien du saké. Même "personnel" des projets que je fais sur mon temps juste pour moi-même, j'essaie de javadoc juste parce que je pourrais plateau pendant un an et revenez-y plus tard.

    InformationsquelleAutor CodingWithSpike
  19. 0

    Supposé dans toutes les réponses jusqu'à présent est que les commentaires seront de bons commentaires. Comme nous savons tous que c'est pas toujours le cas, parfois, ils sont même incorrect. Si vous devez lire le code pour déterminer son intention, les limites, et de l'erreur attendue comportement, alors le commentaire est en manque. Par exemple, est la méthode thread-safe, peut-arg être null, peut-il retourner la valeur null, etc. Les commentaires devraient faire partie de toute révision du code.

    Ce pourrait être encore plus important pour les méthodes privées depuis un responsable de la base de code devront composer avec les questions qu'un utilisateur API ne sera pas.

    Peut-être IDEs doit avoir une fonctionnalité qui permet l'utilisation d'une documentation afin que les développeurs peuvent cocher plusieurs propriétés qui sont importants et applicables pour la méthode actuelle.

    InformationsquelleAutor Josef.B