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

https://stackoverflow.com/questions/211041

03-07-2019
|

Question

Devrais-je écrire des commentaires Doc pour toutes mes méthodes java?

La solution

@Claudiu

Quand j'écris du code que d'autres vont utiliser - Oui. Toute méthode pouvant être utilisée par une autre personne (toute méthode publique) doit comporter au moins un javadoc indiquant son objectif évident.

@Daniel Spiewak

Je documente minutieusement chaque méthode publique dans chaque classe d'API. Les classes qui ont des membres publics mais qui ne sont pas destinées à une consommation externe sont clairement indiquées dans la classe javadoc. Je documente également chaque méthode protégée dans chaque classe d'API, bien que dans une moindre mesure. Cela va dans l’idée que tout développeur qui étend une classe d’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 Je pense que toute méthode ou champ nécessitant une explication dans son utilisation recevra une documentation, quelle que soit sa visibilité.

@Paul de Vrieze

Pour les choses, comme les getters et les setters triviaux, partagez le commentaire entre-temps et décrivez le but de la propriété, pas celui 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 extrêmement complexe (en raison de la complexité cyclomatique élevée raison) dans:

une méthode publique appelant
plusieurs méthodes privées qui représentent les étapes internes de la méthode publique

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

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

De plus, javadoc est bien meilleur que le simple "// commentaire" :

Il est reconnu par l'IDE et utilisé pour afficher une fenêtre contextuelle lorsque vous déplacez votre curseur au-dessus de 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 anodine. Exemple: regexp (son javadoc devrait inclure l’expression rationnelle sous sa forme non échappée, son objet et un exemple littéral correspondant à l’expression rationnelle)
Il peut être analysé par des outils externes (tels que xdoclet )

@Domci

Pour moi, si quelqu'un le voit ou pas, 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, la logique de commentaire, pas la syntaxe, et ne le faites qu’une fois, à la place appropriée.

@Miguel Ping

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

Autres conseils

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

Des commentaires du genre

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

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

Je documente de manière approfondie chaque méthode publique de chaque classe d'API. Les classes qui ont des membres publics mais qui ne sont pas destinées à une consommation externe sont clairement indiquées dans la classe javadoc. Je documente également chaque méthode protégée dans chaque classe d'API, bien que dans une moindre mesure. Cela va dans l’idée que tout développeur qui étend une classe d’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. Je pense que toute méthode ou champ nécessitant une explication dans son utilisation recevra une documentation, quelle que soit sa visibilité.

Pour les choses, comme les getters et les setters triviaux, partagez le commentaire entre-temps et décrivez le but de la propriété, pas du getter / setter.

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

Est-ce que 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 sont déjà couvertes par d’autres; une note supplémentaire:

Si vous vous trouvez en train de faire ceci:

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

Envisagez de 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 souhaité; par exemple, on peut s’attendre à ce que le comportement de la méthode évolue dans le temps (notez le mot "actuellement" dans le JavaDoc).

Non, ne commentez pas toutes les méthodes, variables, classes, etc.

Voici une citation de "Clean Code: Manuel sur la maîtrise technique agile des logiciels":

Il est tout simplement ridicule d’avoir une règle qui dit que chaque fonction doit avoir un javadoc, ou chaque variable doit avoir un commentaire. Des commentaires comme ce fouillis le code, popagate mensonges, et prêtent à la confusion générale et la désorganisation.

Un commentaire doit exister si, et seulement si, il ajoute des informations importantes à l'utilisateur prévu de la méthode, de la variable, de la classe, etc. Ce qui constitue "important" " mérite d’être pris en considération et pourrait me rappeler quand / si je reviens à cette méthode / classe / etc., une conséquence / un effet secondaire de la méthode, motivation pour laquelle la chose existe même une lacune / un bogue d’une bibliothèque ou d’un système), des informations importantes sur la représentation ou le moment approprié pour appeler, etc.

Ce qui n'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 fonction complexe et obscure. Préférez plutôt un code plus clair et 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 pensez à ce que fait la méthode / fonction / classe, ce qui vous rend plus précis et clair dans votre javadoc, ce qui vous permet d'écrire plus clairement. et un code concis, ce qui est bon.

Lorsque 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 utiliseront - Oui . Toute méthode pouvant être utilisée par une autre personne (toute méthode publique) doit comporter au moins un document Java indiquant son objectif évident. Pour un bon test, lancez l’utilitaire de création javadoc sur votre code (j’oublie la ligne de commande exacte maintenant). 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 or. Si ce n'est pas le cas, écrivez davantage de javadocs dans votre code .

Pour moi, si quelqu'un le voit ou pas, 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 existe quelques directives:

Les API, les classes de structure et les méthodes statiques internes réutilisables doivent être commentées en détail.
La logique dans chaque morceau de code complexe 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, il est inutile de commenter le nom d'utilisateur et le mot de passe, mais le type doit au moins comporter un commentaire indiquant les valeurs possibles pour le type.
Je ne documente pas les getters, les setters ni rien de ce qui est fait "par le livre". Si l'équipe dispose d'un moyen 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 ce à quoi elle est destinée - en supposant que la philosophie du framework et sa façon de travailler soient documentées quelque part. Dans ce cas, les commentaires signifient un fouillis supplémentaire et n’ont aucune utilité. Il y a des exceptions à cela lorsque la classe fait quelque chose de non standard - alors un court commentaire est utile. De plus, même si je crée un formulaire de manière standard, j'aime diviser les parties du formulaire avec de courts commentaires divisant le code en plusieurs parties, par exemple "l'adresse de facturation commence ici".

En bref, la logique de commentaire, pas la syntaxe, et ne le faites qu'une seule fois, à la place appropriée.

On ne doit pas se fier à la documentation Java, car elle incombe aux développeurs qui font des modifications pour gérer la documentation Java ainsi que le code.

Les noms de classe et de fonction doivent être suffisamment explicites pour expliquer ce qui se passe.

Si pour expliquer ce qu'une classe ou une méthode rend son nom trop long à traiter, la classe ou la méthode n'est pas suffisamment focalisée et doit être refactorisée en unités plus petites.

tout simplement: OUI

l'heure à laquelle vous devez réfléchir à la rédaction d'un document, est mieux investi dans la rédaction d'un document.

Écrire une ligne est préférable à perdre du temps à ne pas documenter la méthode à la fin.

Je pense qu’il devrait au moins y avoir des commentaires sur les paramètres acceptés et les types de retour en termes de ce qu’ils sont.
Vous pouvez ignorer les détails d'implémentation au cas où le nom de la fonction le décrit complètement, par exemple, sendEmail (..) ;

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, bien que je pense qu'elles devraient l'être, pour que ce soit plus clair - il en va de même pour les méthodes protégées. Vos commentaires doivent être informatifs et ne pas se contenter de rappeler 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 de ne pas nécessiter de commentaires. Toutefois, comme ce n’est pas toujours possible, les 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 afin de réduire la quantité de documentation à écrire. Une autre astuce consiste à utiliser le @ {$ inheritDoc} pour éviter 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 hérité avec Javadocs, pouvez-vous compter sur cela? Je ne le pense pas ... Quelqu'un a ajouté Javadoc, puis la mise en œuvre a été modifiée, une nouvelle fonctionnalité a été ajoutée (supprimée), de sorte que le Javadoc est devenu obsolète. Comme je l’ai mentionné plus tôt, j’aime les javadocs pour les bibliothèques, mais je préférerais les projets actifs

petites fonctions / classes avec des noms décrivant ce qu'elles font
effacer les cas de tests unitaires qui donnent une explication de ce que le fonction / classes faire

chez une société précédente, nous utilisions le formateur de code jalopy avec eclipse. Cela ajouterait du javadoc à toutes les méthodes, y compris les méthodes privées.

Cela rendait la vie difficile pour documenter les setters et les getters. Mais que diable. Vous devez le faire - vous le faites. Cela m'a fait apprendre certaines fonctionnalités de macro avec XEmacs :-) Vous pouvez l'automatiser encore plus en écrivant un analyseur et un commentateur java comme le créateur d'ANTLR l'avait fait il y a plusieurs années: -)

Actuellement, je documente toutes les méthodes publiques et tout ce qui dépasse 10 lignes.

Je me fais un devoir d’écrire des commentaires javadoc chaque fois que ce n’est pas trivial. Ecrire 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 êtes obligé de penser non seulement à ce que la méthode fait, mais à ce que fait la méthode exactement , ainsi qu’aux hypothèses que vous avez faites.

Une autre raison est qu’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 vos méthodes font, mais je préfère simplement me souvenir d'autres choses plus importantes.

Vous pouvez exécuter javadoc avec du code ne contenant pas de commentaires javadoc. Il produira des javadocs relativement utilisables si vous attribuez des noms réfléchis à vos méthodes et paramètres.

J'essaie au moins de documenter chaque propriété et méthode publique et d'interface, afin 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 fais juste pour moi-même, j'essaie de javadoc simplement parce que je pourrais le conserver pendant un an et y revenir plus tard.

On suppose dans toutes les réponses jusqu’à présent que les commentaires seront de bons commentaires. Comme nous savons tous que ce n’est pas toujours le cas, ils sont parfois même incorrects. Si vous devez lire le code pour déterminer son intention, ses limites et le comportement d'erreur attendu, le commentaire fait défaut. Par exemple, la méthode est-elle sécurisée, un argument peut-il être null, peut-il renvoyer une valeur nulle, etc. Les commentaires doivent faire partie des révisions de code.

Cela peut être encore plus important pour les méthodes privées puisqu'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é permettant d'utiliser un formulaire de documentation afin que le développeur puisse cocher diverses propriétés importantes et applicables à la méthode actuelle.

Licencié sous: CC-BY-SA avec attribution

Non affilié à StackOverflow