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?
Réponses:
Pour les méthodes d'implémentation uniquement (pas de substitution), 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. En conséquence, 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. Utiliser @inheritDocou ne pas fournir de documentation - Les IDE prendront le texte le plus bas disponible à utiliser dans leur vue Javadoc.
En passant, si votre version de remplacement ajoute des éléments à la documentation du supertype, vous pourriez être dans un monde de problèmes. J'ai étudié ce problème au cours de mon doctorat et j'ai découvert qu'en général, les gens ne seront jamais conscients des informations supplémentaires dans la version de remplacement 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 potentielle de priorité contenait des informations importantes (par exemple, un comportement conflictuel). Par exemple, lors de l'invocation de put sur une carte, il vous a été rappelé que si votre implémentation est une TreeMap, vos éléments doivent être comparables.
L'implémentation et l'interface doivent 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)
{ ... }
{@inheritDoc}et il ne fonctionne que si vous n'avez l'annotation première@Override
Une bonne pratique consiste à mettre
/**
* {@inheritDoc}
*/
comme javadoc de l'implémentation (à moins qu'il y ait quelque chose de plus à expliquer sur les détails de l'implémentation).
En général, lorsque vous remplacez une méthode, vous adhérez au contrat défini dans la classe / interface de base, vous ne voulez donc pas changer le javadoc d'origine de toute façon. Par conséquent, l'utilisation de @inheritDocou de la @seebalise mentionnée dans d'autres réponses n'est pas nécessaire et ne sert en fait que de bruit dans le code. Tous les outils sensibles 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 souhaitez réellement ajouter un commentaire à la méthode de substitution (généralement des détails d'implémentation supplémentaires ou en rendant 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 éventuellement ê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 ne sert à rien 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 quelques détails sur la mise en œuvre.
@seeméthodes de liaison aux interfaces est une bonne pratique et cela suffit dans la plupart des cas. Lorsque vous copiez javadoc d'une méthode d'interface vers une implémentation concrète, vous ne faites que dupliquer des informations et cela peut rapidement devenir incohérent. Cependant, toute information supplémentaire sur l'implémentation doit être ajoutée à javadoc.
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 renvoyer et ce qu'elle doit faire en cas d'erreur.
La documentation de mise en œuvre doit noter les extensions ou les restrictions du contrat, ainsi que les détails appropriés de la mise en œuvre, en particulier les performances.
Pour le bien du javadoc généré, oui, c'est important. Si vous déclarez des références à une implémentation concrète en utilisant uniquement l'interface, ce n'est pas le cas puisque les méthodes de l'interface seront récupérées par l'EDI.