Utilisez-vous Javadoc pour chaque méthode que vous écrivez?

Devrais-je écrire Doc Comments pour toutes mes méthodes Java?

@Claudiu

Lorsque j’écris du code que d’autres vont utiliser – Oui. Chaque méthode que quelqu’un d’autre peut utiliser (n’importe quelle méthode publique) devrait avoir au moins un javadoc indiquant son objective évident.

@Daniel Spiewak

Je documente complètement chaque méthode publique dans chaque classe d’API. Les classes qui ont des membres publics mais qui ne sont pas destinées à la consommation externe sont clairement indiquées dans la classe javadoc. Je documente également chaque méthode protégée dans chaque classe d’API, mais dans une moindre mesure. Cela passe par l’idée que tout développeur qui étend une classe d’API aura déjà un concept juste de ce qui se passe.

Enfin, je documenterai occasionnellement des méthodes privées et privées pour mon propre compte. Toute méthode ou champ qui, selon moi, nécessite une explication dans son utilisation recevra la documentation, quelle que soit sa visibilité.

@ Paul de Vrieze

Pour les choses, comme les getters et les setters sortingviaux, partagez le commentaire entre eux et décrivez le but de la propriété, pas du 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 une méthode complexe énorme (en raison de la raison de la complexité cyclomatique élevée ) en:

  • une méthode publique appelant
  • plusieurs méthodes privées qui représentent les étapes internes du public

, il est très utile également de javadoc les méthodes privées, même si cette documentation ne sera pas visible dans les fichiers de l’API javadoc.
Cependant, il vous permet de vous rappeler plus facilement la nature précise des différentes étapes de votre algorithme complexe.

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

De plus, javadoc est bien meilleur que le simple “// comment” :

  • Il est reconnu par IDE et utilisé pour afficher une fenêtre contextuelle lorsque vous déplacez votre curseur sur l’une de vos fonctions javadoc-ed. Par exemple, une constante – c’est-à-dire une variable finale statique privée – devrait avoir un javadoc, en particulier lorsque sa valeur n’est pas sortingviale. Exemple de cas: regexp (son javadoc devrait inclure l’expression rationnelle dans sa forme non échappée, quel est son objective et un exemple littéral correspondant à l’expression rationnelle)
  • Il peut être analysé par des outils externes (comme xdoclet )

@Domci

Pour moi, si quelqu’un le voit ou pas, peu importe – il est peu probable que je sache ce que j’ai écrit après quelques mois. […]
En bref, commentez la logique, pas la syntaxe, et ne le faites qu’une seule fois, au bon endroit.

@Miguel Ping

Pour commenter quelque chose, vous devez d’abord le comprendre. Lorsque vous essayez de commenter une fonction, vous réfléchissez réellement à ce que fait la méthode / fonction / classe, et cela vous rend plus précis et plus clair dans votre javadoc, ce qui vous permet d’écrire du code plus clair et concis, ce qui est bien .

Si la méthode est évidemment évidente, je pourrais sauter un commentaire javadoc.

Des commentaires comme

  / ** Foo * /
  annuler doFoo ();

Ce n’est vraiment pas utile. (Exemple trop simpliste, mais vous avez l’idée)

Je documente complètement chaque méthode publique dans chaque classe d’API. Les classes qui ont des membres publics mais qui ne sont pas destinées à la consommation externe sont clairement indiquées dans la classe javadoc. Je documente également chaque méthode protégée dans chaque classe d’API, mais dans une moindre mesure. Cela passe par l’idée que tout développeur qui étend une classe d’API aura déjà un concept juste de ce qui se passe.

Enfin, je documenterai occasionnellement des méthodes privées et privées pour mon propre compte. Toute méthode ou champ qui, selon moi, nécessite une explication dans son utilisation recevra la documentation, quelle que soit sa visibilité.

Car les choses, comme les getters et les setters sortingviaux, partagent le commentaire entre eux et décrivent le but de la propriété, pas du getter / setter.

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

N’est pas utile Mieux vaut 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.

Toutes les bases couvertes par d’autres déjà; une note supplémentaire:

Si vous vous trouvez faire ceci:

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

Pensez à le changer en ceci:

 void launchBlaardhIntoBleeyrg() { ... } 

Cela peut sembler un peu évident, mais dans de nombreux cas, il est facile de rater l’occasion dans votre propre code.

Enfin, gardez à l’esprit que le changement n’est pas toujours souhaité. Par exemple, le comportement de la méthode peut évoluer avec le temps (notez le mot “actuellement” dans JavaDoc).

Non, ne commentez pas chaque méthode, variable, classe, etc.

Voici une citation de “Clean Code: Un manuel de l’artisanat agile”:

Il est tout à fait idiot d’avoir une règle qui dit que chaque fonction doit avoir un javadoc, ou chaque variable doit avoir un commentaire. Des commentaires comme celui-ci ne font qu’aggraver le code, déployer des mensonges et donner lieu à une confusion et à une désorganisation générales.

Un commentaire devrait exister si, et seulement si, il ajoute des informations importantes pour l’utilisateur visé de la méthode, de la variable, de la classe, etc. Ce qui constitue “important” mérite d’être considéré et pourrait me rappeler quand / si je reviens à cette méthode / classe / etc., une conséquence / effet secondaire de la méthode, la motivation pour laquelle la chose existe (dans le cas où un code surmonte une lacune / un bug de certaines bibliothèques ou systèmes), des informations importantes sur la performance ou quand il convient d’appeler, etc.

Ce qui n’est pas un bon commentaire mais indique que le code lui-même devrait être réécrit / modifié est un commentaire expliquant les détails d’une méthode ou d’une fonction complexe et obscure. Au lieu de cela, préférez un code plus clair plus court.

Il y a une autre raison pour laquelle vous devriez utiliser javadocs. Pour commenter quelque chose, vous devez d’abord le comprendre. Lorsque vous essayez de commenter une fonction, vous réfléchissez réellement à ce que fait la méthode / fonction / classe, et cela vous rend plus précis et plus clair dans votre javadoc, ce qui vous permet d’écrire du code plus clair et concis, ce qui est bien .

Quand j’écris du code pour moi-même – NON . Dans ce cas, java doccing est une perte de temps.

Lorsque j’écris du code que d’autres vont utiliser – Oui . Chaque méthode que quelqu’un d’autre peut utiliser (n’importe quelle méthode publique) devrait avoir au moins un document Java indiquant son objective évident. Pour un bon test, lancez l’utilitaire de création javadoc sur votre code (j’oublie maintenant la ligne de commande exacte). Parcourez la page Web générée. Si vous êtes satisfait d’utiliser une bibliothèque avec ce niveau de documentation, vous êtes en bonne position. Sinon, écrivez plus de javadocs dans votre code .

Pour moi, si quelqu’un le voit ou pas, peu importe – il est peu probable que je sache ce que j’ai écrit après quelques mois. Il y a quelques lignes direcsortingces:

  1. Les API, les classes d’infrastructure et les méthodes statiques internes réutilisables doivent faire l’object de commentaires approfondis.

  2. La logique dans chaque morceau de code compliqué doit être expliquée à deux endroits – la logique générale dans javadoc et la logique pour chaque partie significative du code dans son propre commentaire.

  3. Les propriétés du modèle doivent être commentées si elles ne sont pas évidentes. Par exemple, inutile de commenter le nom d’utilisateur et le mot de passe, mais le type doit au moins contenir un commentaire indiquant quelles sont les valeurs possibles pour le type.

  4. Je ne documente pas les getters, les setters ou tout ce qui est fait “par le livre”. Si l’équipe dispose d’une méthode standard pour créer des formulaires, des adaptateurs, des contrôleurs, des façades … Je ne les documente pas, car il est inutile que tous les adaptateurs soient identiques et disposent d’un ensemble de méthodes standard. Quiconque connaît le framework saura ce qu’il cherche – en supposant que la philosophie du framework et sa manière de travailler soient documentées quelque part. Dans ce cas, les commentaires signifient un encombrement supplémentaire et ne servent à rien. Il y a des exceptions à cela lorsque la classe fait quelque chose de non standard – alors un court commentaire est utile. Aussi, même si je crée un formulaire de manière standard, j’aime diviser des parties du formulaire avec de courts commentaires qui divisent le code en plusieurs parties, par exemple “l’adresse de facturation commence ici”.

En bref, commentez la logique, pas la syntaxe, et ne le faites qu’une seule fois, au bon endroit.

Java doc ne doit pas être utilisé, car cela oblige les développeurs à apporter des modifications pour gérer le doc java ainsi que le code.

Les noms de classes et les noms de fonctions doivent être suffisamment explicites pour expliquer ce qui se passe.

Si expliquer pourquoi une classe ou une méthode rend son nom trop long, la classe ou la méthode n’est pas suffisamment ciblée et doit être restructurée en unités plus petites.

mettez simplement: OUI

Le temps dont vous avez besoin pour réfléchir à la possibilité d’écrire un doc est mieux investi dans la rédaction d’un document.

Écrire un papier à un trait vaut mieux que passer du temps à ne pas documenter la méthode du tout.

Je pense qu’il devrait y avoir au moins des commentaires concernant les parameters acceptés et les types de retour en termes de ce qu’ils sont.
On peut ignorer les détails d’implémentation au cas où les noms de fonctions le décrivent complètement, par exemple, sendEmail (..) ;

Vous devriez probablement documenter toutes vos méthodes. Les plus importantes sont les méthodes API publiques (en particulier les méthodes API publiées). Les méthodes privées ne sont parfois pas documentées, bien que je pense qu’elles devraient l’être, juste pour plus de clarté – il en va de même pour les méthodes protégées. Vos commentaires doivent être informatifs et ne pas simplement répéter ce que fait le code.

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

Vous pouvez automatiser la génération de commentaires Javadoc pour les getters / setters à partir d’Eclipse via les modèles de code afin d’économiser la quantité de documentation à écrire. Une autre astuce consiste à utiliser le @ {$ inheritDoc} pour empêcher la duplication des commentaires de code entre les interfaces et les classes d’implémentation.

Javadoc peut être très utile pour les bibliothèques et les composants réutilisables. Mais soyons plus pratiques. Il est plus important d’avoir un code explicite que javadoc. Si vous imaginez un énorme projet avec Javadocs – feriez-vous confiance à cela? Je ne le pense pas … Quelqu’un a ajouté Javadoc, puis l’implémentation a changé, une nouvelle fonctionnalité a été ajoutée (supprimée), donc le Javadoc est devenu obsolète. Comme je l’ai mentionné, j’aime bien avoir des javadocs pour les bibliothèques, mais pour des projets actifs, je préférerais

  • petites fonctions / classes avec des noms qui décrivent ce qu’elles font
  • effacer les cas tests unitaires qui expliquent ce que font les fonctions / classes

dans une entreprise précédente, nous utilisions le formateur de code jalopy avec eclipse. Cela appendait javadoc à toutes les méthodes, y compris privées.

Cela a rendu la vie difficile à documenter les établissements et les getters. Mais que diable? Vous devez le faire – vous le faites. Cela m’a fait apprendre quelques fonctionnalités de macro avec XEmacs 🙂 Vous pouvez automatiser encore plus en écrivant un parsingur et un commentateur java comme le créateur d’ANTLR l’a fait il y a plusieurs années 🙂

Actuellement, je documente toutes les méthodes publiques et plus de 10 lignes.

Je me fais un devoir d’écrire des commentaires javadoc chaque fois qu’il n’est pas sortingvial, écrire des 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 devez penser non seulement à ce que fait la méthode, mais aussi à ce que fait exactement la méthode et aux hypothèses que vous avez formulées.

Une autre raison est que, une fois que vous avez compris votre code et qu’il a été remanié, le javadoc vous permet d’oublier ce qu’il fait car vous pouvez toujours vous y référer. Je ne préconise pas d’oublier délibérément ce que font vos méthodes, mais c’est simplement que je préfère me souvenir d’autres choses plus importantes.

Vous pouvez exécuter javadoc contre du code sans commentaires javadoc et cela produira des javadocs assez utilisables si vous donnez des noms réfléchis à vos méthodes et parameters.

J’essaie au moins de documenter chaque propriété et méthode publique et d’interface, de sorte que les personnes appelant dans mon code sachent ce que sont les choses. J’essaie également de commenter autant que possible en ligne pour des raisons de maintenance. Même les projets «personnels» que je réalise pendant mon temps libre pour moi-même, j’essaie de javadocer parce que je pourrais l’étaler pendant un an et y revenir plus tard.

Dans toutes les réponses, on peut supposer que les commentaires seront de bons commentaires. Comme nous le soaps tous, ce n’est pas toujours le cas, parfois ils sont même incorrects. Si vous devez lire le code pour déterminer son intention, ses limites et son comportement d’erreur attendu, le commentaire fait défaut. Par exemple, la méthode thread thread est-elle sûre, tout argument peut-il être nul, peut-il renvoyer null, etc. Les commentaires doivent faire partie de toutes les révisions de code.

Cela peut être encore plus important pour les méthodes privées, car un responsable de la base de code devra faire face à des problèmes qui ne seront pas rencontrés par un utilisateur de l’API.

Les IDE peuvent peut-être avoir une fonctionnalité qui permet d’utiliser un formulaire de documentation afin que le développeur puisse vérifier les différentes propriétés importantes et applicables pour la méthode actuelle.