Utilisez-vous Javadoc pour chaque méthode que vous écrivez?
Dois-je écrire des commentaires de doc pour toutes mes méthodes Java?
@Claudiu
Quand j'écris du code que d'autres utiliseront - Oui. Chaque méthode que quelqu'un d'autre peut utiliser (n'importe quelle méthode publique) devrait avoir un javadoc indiquant au moins son objectif évident.
@Daniel Spiewak
Je documente en détail chaque méthode publique dans chaque classe d'API. Les classes qui ont des membres publics mais qui ne sont pas destinés à la consommation externe sont marquées en évidence dans la classe javadoc. Je documente également chaque méthode protégée dans chaque classe d'API, mais dans une moindre mesure. Cela part de l'idée que tout développeur qui étend une classe API aura déjà une idée juste de ce qui se passe.
Enfin, je documenterai occasionnellement des méthodes privées et des méthodes privées pour mon propre bénéfice. Toute méthode ou tout domaine qui, selon moi, a besoin d'explications dans son utilisation recevra une documentation, quelle que soit sa visibilité.
@Paul de Vrieze
Pour les choses, comme les getters et setters triviaux, partagez le commentaire entre-temps et décrivez le but de la propriété, pas celle 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 énorme méthode complexe (en raison de complexité cyclomatique élevée raison) en:
- une méthode publique appelant
- plusieurs méthodes privées qui représentent des étapes internes de la publique
, il est également très utile de javadocer les méthodes privées, même si cette documentation ne sera pas visible dans les fichiers API javadoc.
Néanmoins, il vous permet de vous souvenir plus facilement de la nature précise des différentes étapes de votre algorithme complexe.
Et n'oubliez pas: valeurs limites ou conditions aux limites devrait également faire partie de votre javadoc.
De plus, javadoc est bien meilleur qu'un simple "// commentaire":
- 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 - qui est une variable finale statique privée -, devrait avoir un javadoc, surtout lorsque sa valeur n'est pas triviale. Exemple: regexp (son javadoc devrait inclure l'expression régulière dans sa forme non échappée, quel est le but est 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 verra ou non, cela n'a pas d'importance - il est peu probable que je sache ce que fait un morceau de code obscur que j'ai écrit après quelques mois. [...]
En bref, commentez la logique, pas la syntaxe, et faites-le une seule fois, à un endroit approprié.
@Miguel Ping
Pour commenter quelque chose, vous devez d'abord le comprendre. Lorsque vous essayez de commenter une fonction, vous pensez en fait à ce que fait la méthode/fonction/classe, et cela vous rend plus précis et clair dans votre javadoc, ce qui vous fait à son tour écrire du code plus clair et concis, ce qui est bien .
Si la méthode est évidente, je pourrais sauter un commentaire javadoc.
Des commentaires comme
/ ** Est-ce que Foo */ Annule doFoo ();
Ce n'est vraiment pas très utile. (Exemple trop simpliste, mais vous avez l'idée)
I minutieusement documente chaque méthode publique dans chaque classe d'API. Les classes qui ont des membres publics mais qui ne sont pas destinés à la consommation externe sont marquées en évidence dans la classe javadoc. Je documente également chaque méthode protégée dans chaque classe d'API, mais dans une moindre mesure. Cela part de l'idée que tout développeur qui étend une classe API aura déjà une idée juste de ce qui se passe.
Enfin, je documenterai occasionnellement des méthodes privées et des méthodes privées à mon avantage. Toute méthode ou tout domaine qui, selon moi, a besoin d'explications dans son utilisation recevra une documentation, quelle que soit sa visibilité.
Pour les choses, comme les getters et setters triviaux, partagez le commentaire entre les deux et décrivez le but de la propriété, pas celle du getter/setter.
/**
* Get foo
* @return The value of the foo property
*/
int getFoo() {
return foo;
}
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 sont déjà couvertes par d'autres; une remarque supplémentaire:
Si vous vous trouvez en train de 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, l'occasion est facile à manquer dans votre propre code.
Enfin, gardez à l'esprit que le changement n'est pas toujours voulu; par exemple, on peut s'attendre à ce que le comportement de la méthode évolue avec le temps (notez le mot "actuellement" dans JavaDoc).
Non, ne commentez pas toutes les méthodes, variables, classes, etc.
Voici une citation de "Code propre: un manuel de l'artisanat logiciel Agile":
Il est tout simplement stupide 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'encombrer le code, peupler les mensonges et prêter à confusion et désorganisation générales.
Un commentaire doit exister si, et seulement si, il ajoute des informations importantes pour l'utilisateur prév de la méthode, variable, classe, etc. Ce qui constitue "important" mérite d'être considéré et pourrait être un rappel moi-même quand/si je reviens à cette méthode/classe/etc. ), des informations importantes sur la performance ou quand il convient d'appeler, etc.
Ce qui est pas un bon commentaire mais indique que le code lui-même doit ê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 court et plus clair.
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 êtes en fait en pensant à ce que fait la méthode/fonction/classe, et cela vous rend plus précis et clair dans votre javadoc, ce qui à son tour vous fait écrire plus clairement et un code concis, ce qui est bien.
Quand j'écris du code pour moi - NON. Dans ce cas, Java doccing est une perte de temps.
Quand j'écris du code que d'autres utiliseront - Oui. Chaque méthode que quelqu'un d'autre peut utiliser (n'importe quelle méthode publique) doit avoir un document Java indiquant au moins son objectif évident. Pour un bon test - exécutez l'utilitaire de création javadoc sur votre code (j'oublie le ligne de commande exacte maintenant.) Parcourez la page Web qu'elle génère. Si vous êtes satisfait d'utiliser une bibliothèque avec ce niveau de documentation, vous êtes en or. Sinon, Écrivez plus de javadocs dans votre code.
Pour moi, si quelqu'un le verra ou non, cela n'a pas d'importance - il est peu probable que je sache ce que fait un morceau de code obscur que j'ai écrit après quelques mois. Il y a quelques directives:
Les API, les classes de framework et les méthodes statiques réutilisables internes doivent être commentées en détail.
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.
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 avoir un commentaire qui indique quelles sont les valeurs possibles pour le type.
Je ne documente pas les getters, les setters ou tout ce qui est fait "par le livre". Si l'équipe a une façon standard de 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. Toute personne familiarisée avec le framework saura à quoi elle sert - en supposant que la philosophie du framework et la manière de travailler avec lui soient documentées quelque part. Dans ce cas, les commentaires signifient un encombrement supplémentaire et n'ont aucun sens. Il y a des exceptions à cela lorsque la classe fait quelque chose de non standard - alors un bref commentaire est utile. De plus, 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.
La documentation Java ne doit pas être invoquée, car elle impose une charge aux développeurs apportant des modifications pour maintenir la documentation Java ainsi que le code.
Les noms de classe et les noms de fonction doivent être suffisamment explicites pour expliquer ce qui se passe.
Si, pour expliquer ce qu'une classe ou une méthode fait, son nom est trop long à traiter, la classe ou la méthode n'est pas suffisamment ciblée et doit être refactorisée en unités plus petites.
Je pense qu'il devrait au moins y avoir des commentaires concernant les paramètres acceptés et les types de retour en fonction de ce qu'ils sont.
On peut ignorer les détails de l'implémentation au cas où les noms de fonction le décrivent complètement, par exemple, sendEmail (..);
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 du code explicatif que javadoc. Si vous imaginez un énorme projet hérité avec Javadocs - vous feriez-vous confiance? Je ne 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 avoir des javadocs pour les bibliothèques, mais pour les projets actifs, je préférerais
- petites fonctions/classes avec des noms qui décrivent ce qu'ils font
- des cas de tests unitaires clairs qui expliquent ce que font les fonctions/classes
Vous devriez probablement documenter vraiment 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, même si 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éitérer 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 afin qu'il ne nécessite pas de commentaires. Cependant, ce n'est pas toujours possible, donc des commentaires doivent ê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 pour économiser sur la quantité de documentation que vous devez écrire. une autre astuce consiste à utiliser @ {$ inheritDoc} pour éviter la duplication des commentaires de code entre les interfaces et les classes d'implémentation.
mettez simplement: OUI
Le temps dont vous avez besoin pour réfléchir à l'opportunité d'écrire un doc est mieux investi dans l'écriture d'un doc.
Écrire un one-liner est mieux que de passer du temps à ne pas documenter la méthode du tout à la fin.
Supposé dans toutes les réponses jusqu'à présent, les commentaires seront de bons commentaires. Comme nous le savons 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 manque. Par exemple, la méthode est-elle sûre pour les threads, n'importe quel argument peut-il être nul, peut-il retourner nul, etc. Les commentaires doivent faire partie de toute révision 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 qu'un utilisateur d'API ne rencontrera pas.
Peut-être que les IDE devraient avoir une fonctionnalité qui permet l'utilisation d'un formulaire de documentation afin que le développeur puisse cocher diverses propriétés qui sont importantes et applicables pour la méthode actuelle.
Vous pouvez exécuter javadoc contre du code qui n'a pas de commentaires javadoc et il produira des javadocs assez utilisables si vous donnez des noms réfléchis à vos méthodes et paramètres.
Je tiens à écrire des commentaires javadoc chaque fois que cela n'est pas trivial, L'écriture de commentaires javadoc lors de l'utilisation d'un IDE comme Eclipse ou netbeans n'est pas si gênant. En outre, lorsque vous écrivez un commentaire javadoc , vous êtes obligé de penser non seulement à ce que fait la méthode, mais à ce que fait la méthode exactement, et aux hypothèses que vous avez faites.
Une autre raison est qu'une fois que vous avez compris et refactorisé votre code, le javadoc vous permet d'oublier ce qu'il fait puisque 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 juste que je préfère me souvenir d'autres choses qui sont plus importantes.
J'essaie à tout le moins de documenter chaque propriété et méthode publique et d'interface, afin que les personnes qui appellent mon code sachent ce que sont les choses. J'essaie également de commenter autant que possible en ligne ainsi pour des raisons de maintenance. Même les projets "personnels" que je fais sur mon propre temps juste pour moi-même, j'essaie de javadoc juste parce que je pourrais le conserver pendant un an et y revenir plus tard.
dans une entreprise précédente, nous utilisions le formateur de code jalopy avec Eclipse. Cela ajouterait javadoc à toutes les méthodes, y compris private.
Cela a rendu la vie difficile de documenter les setters et les geters. Mais que diable. Vous devez le faire - vous le faites. Cela m'a fait apprendre quelques fonctionnalités de macro avec XEmacs :-) Vous pouvez l'automatiser encore plus en écrivant un Java comme le créateur d'ANTLR a fait il y a plusieurs années :-)
actuellement, je documente toutes les méthodes publiques et plus de 10 lignes.