Commentaires Javadoc vs commentaires de bloc?
Quand est-il approprié d'utiliser un commentaire de bloc au début des méthodes, et quand est-il approprié d'utiliser un commentaire de style javadoc?
Dans la section "Commentaires" du Guide de style Java , j'ai trouvé ceci:
Les programmes Java peuvent avoir deux types de commentaires: les commentaires d'implémentation et les commentaires de documentation. Les commentaires d'implémentation sont ceux trouvés en C++, délimités par
/*...*/, et //. Les commentaires de documentation (appelés "commentaires de doc") sont uniquement Java et sont délimités par/**...*/. Les commentaires de doc peuvent être extraits dans des fichiers HTML à l'aide de l'outil javadoc.Les commentaires d'implémentation sont destinés à commenter le code ou à commenter l'implémentation particulière. Les commentaires de doc sont destinés à décrire la spécification du code, dans une perspective sans implémentation. à lire par les développeurs qui n'ont pas nécessairement le code source à portée de main.
Ainsi, une autre façon de formuler ma question serait: quand les méthodes méritent-elles une spécification du code, dans une perspective sans implémentation (Javadoc) au lieu d'un commentaire sur une implémentation particulière, et vice versa? Une interface obtiendrait-elle des commentaires javadoc, tandis que les implémentations recevraient des commentaires de bloc?
edit: Je pense que je ne transmets pas ma question correctement, sur la base des réponses jusqu'à présent.
Voici un exemple de ce que je veux savoir.
/**
* Javadoc comment here about general implementation?
*/
/*
* Should I now have a separate block comment for my specific implementation?
*/
public void foo()
{
...
}
Les deux styles de commentaires différents véhiculent deux types d'informations différents. Y a-t-il des cas où les méthodes devraient avoir à la fois un commentaire javadoc de tête et un commentaire de bloc de tête?
L'inspiration même pour demander est qu'Eclipse a généré automatiquement ceci pour moi tout à l'heure:
/*
* (non-Javadoc)
* @see my.package#process()
*/
Et je me suis dit qu'il y avait une sorte de style en cours ici qui n'était pas déclaré spécifiquement dans les spécifications de commentaire auxquelles je renvoie ci-dessus.
Les informations que l'utilisateur d'une classe doit connaître doivent être incluses dans un commentaire Javadoc.
Informations qu'un développeur modifiant une classe doit savoir entrer dans un commentaire normal (bloc ou ligne).
Et il est très possible que n'importe quel bloc de code (classe, interface, champ, méthode, constructeur, ...) puisse avoir les deux un commentaire Javadoc et un bloc de commentaire normal, lorsqu'ils sont tous deux visibles publiquement ainsi que une documentation interne est requise.
Personnellement, j'ai tendance à écrire très peu de commentaires non-Javadoc, car je préfère structurer mon code de manière à ce qu'il soit auto-documenté.
À mon avis, les commentaires Javadoc sont des commentaires que vous écrivez aux personnes qui utilisent votre code et qui invoquent vos méthodes.
Les commentaires Javadoc sont plus concentrés sur les paramètres des méthodes, ce que votre méthode retournera en fonction des paramètres que vous donnez à vos méthodes.
Les commentaires de bloc sont des commentaires internes, des commentaires que vous écrivez pour les personnes qui gèrent votre code.
Les commentaires de bloc sont importants pour comprendre comment le code fonctionne, pourquoi il fonctionne et quelles sont les opérations utilisées pour effectuer le travail réel.
À mon avis, cela n'a aucun sens de placer les commentaires de bloc en haut de la méthode (enfin, ne dites jamais jamais mais au moins la plupart du temps). Les commentaires Javadoc sur les méthodes d'interface spécifient le contrat, sur les méthodes de classe, ils parlent de l'implémentation afin qu'un utilisateur puisse décider quelle classe utiliser s'il y a plusieurs classes implémentant une seule interface. Pensez à l'interface List; les implémentations ArrayList et LinkedList sont appropriées dans différents cas d'utilisation, de sorte que leurs documentations respectives peuvent expliquer leurs avantages et leurs inconvénients.
Je bloque les commentaires sur des choses très spécifiques. Je veux le document spécifique à l'implémentation directement où l'implémentation est. Bien sûr, vous devez les utiliser aussi rarement que possible. Utilisez des noms de variable et de méthode expressifs et ils ajoutent automatiquement une documentation de bas niveau.
Les commentaires de bloc générés automatiquement par Eclipse sont à remplir et à faire éventuellement des commentaires Javadoc en ajoutant l'astérisque manquant. Je ne sais pas exactement dans quels cas ils apparaissent, mais l'un est lorsque vous extrayez une interface d'une classe existante. Ensuite, le Javadoc de la classe va à la méthode d'interface et la méthode de classe obtient le commentaire de bloc. Le raisonnement derrière cela est que souvent lors de la mise en œuvre d'une interface, vous n'avez pas vraiment grand-chose à ajouter. Encore une fois, j'utilise List comme exemple. La méthode size() n'aurait plus besoin de documentation dans les implémentations ArrayList et LinkedList. Ils n'ont rien de valeur à ajouter. Bien sûr, cet exemple est artificiel parce que les implémentations réelles (au moins d'OpenJDK) do ont des Javadocs mais je ne vois pas la nécessité de cela et, en fait, n'ajoutent rien de valeur. Pire encore, ils fournissent encore moins d'informations que la documentation de l'interface.