Faut-il ajouter des commentaires Javadoc à la mise en œuvre?
Est-il correct d'ajouter des commentaires Javadoc dans l'interface et d'ajouter des commentaires non Javadoc dans l'implémentation?
La plupart des IDE génèrent des commentaires non JavaDoc pour les implémentations lorsque vous générez automatiquement des commentaires. La méthode concrète ne devrait-elle pas avoir la description?
Pour les méthodes qui sont implémentées uniquement (et non remplacées), bien sûr, pourquoi pas, surtout si elles sont publiques.
Si vous avez une situation primordiale et que vous allez répliquer n'importe quel texte, alors certainement pas. La réplication est un moyen infaillible de provoquer des écarts. Par conséquent, les utilisateurs auraient une compréhension différente de votre méthode selon qu'ils examinent la méthode dans le supertype ou le sous-type. Utilisation @inheritDoc ou ne fournit pas de documentation - Les IDE utiliseront le texte le plus bas disponible à utiliser dans leur vue Javadoc.
En passant, si votre version prioritaire ajoute des éléments à la documentation du supertype, vous pourriez être dans un monde de problèmes. J'ai étudié ce problème pendant ma thèse et j'ai constaté qu'en général, les gens ne seront jamais au courant des informations supplémentaires dans la version prioritaire s'ils invoquent via un supertype.
La résolution de ce problème était l'une des principales caractéristiques de l'outil prototype que j'ai construit - Chaque fois que vous invoquiez une méthode, vous obteniez une indication si sa cible ou toute cible potentiellement prioritaire contenait des informations importantes (par exemple, un comportement conflictuel). Par exemple, lorsque vous appelez put sur une carte, il vous a été rappelé que si votre implémentation est un TreeMap, vos éléments doivent être comparables.
L'implémentation et l'interface devraient avoir javadoc. Avec certains outils, vous pouvez hériter de la documentation de l'interface avec le mot clé @inheritDoc.
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }
Une bonne pratique consiste à mettre
/**
* {@inheritDoc}
*/
comme javadoc de l'implémentation (sauf s'il y a quelque chose de plus à expliquer sur les détails de l'implémentation).
En règle générale, lorsque vous remplacez une méthode, vous respectez le contrat défini dans la classe/interface de base, vous ne voulez donc pas modifier le javadoc d'origine de toute façon. Par conséquent, l'utilisation de @inheritDoc ou @see La balise mentionnée dans les autres réponses n'est pas nécessaire et ne sert en fait que de bruit dans le code. Tous les outils sensés héritent de la méthode javadoc de la superclasse ou de l'interface comme spécifié ici :
Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:
- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface
Le fait que certains outils (je vous regarde, Eclipse!) Les génèrent par défaut lors du remplacement d'une méthode n'est qu'un triste état de choses, mais ne justifie pas d'encombrer votre code avec un bruit inutile.
Il peut bien sûr y avoir le cas contraire, lorsque vous voulez réellement ajouter un commentaire à la méthode prioritaire (généralement des détails d'implémentation supplémentaires ou rendre le contrat un peu plus strict). Mais dans ce cas, vous ne voulez presque jamais faire quelque chose comme ça:
/**
* {@inheritDoc}
*
* This implementation is very, very slow when b equals 3.
*/
Pourquoi? Parce que le commentaire hérité peut être très long. Dans ce cas, qui remarquera la phrase supplémentaire à la fin des 3 longs paragraphes ?? Au lieu de cela, écrivez simplement le morceau de votre propre commentaire et c'est tout. Tous les outils javadoc affichent toujours une sorte de lien spécifié par sur lequel vous pouvez cliquer pour lire le commentaire de la classe de base. Il est inutile de les mélanger.
@see Il génère un lien vers la description dans l'interface. Mais je pense qu'il est bon d'ajouter également des détails sur la mise en œuvre.
Sjoerd dit correctement que l'interface et l'implémentation devraient avoir JavaDoc. L'interface JavaDoc doit définir le contrat de la méthode - ce que la méthode doit faire, quelles entrées elle prend, quelles valeurs elle doit retourner et ce qu'elle doit faire en cas d'erreur.
La documentation de mise en œuvre doit noter les extensions ou restrictions du contrat, ainsi que les détails appropriés de la mise en œuvre, en particulier les performances.
Par souci de javadoc généré oui, cela importe. Si vous déclarez des références à une implémentation concrète en utilisant uniquement l'interface, ce n'est pas le cas car les méthodes de l'interface seront récupérées par l'EDI.