Devrait commentaires Javadoc être ajouté à la mise en œuvre?
Est-il exact pratique pour ajouter des commentaires Javadoc dans l'interface et ajouter des commentaires Javadoc dans la mise en œuvre?
La plupart des IDEs de générer des non-commentaires JavaDoc pour les implémentations lorsque vous générer automatiquement des commentaires. Ne pas le béton méthode la description?
Vous devez vous connecter pour publier un commentaire.
Pour les méthodes de mise en œuvre seulement (pas de dérogation), bien sûr, pourquoi pas, surtout si elles sont publiques.
Si vous avez une bonne situation et vous allez reproduire le texte, puis définitivement pas. La réplication est un moyen infaillible de provoquant. En conséquence, les utilisateurs ont une compréhension différente de la votre méthode basée sur le fait qu'ils examiner la méthode dans le supertype ou le sous-type. Utilisation
@inheritDocou de ne pas fournir de la documentation - Les IDEs prendra le plus de texte à utiliser dans leur Javadoc vue.En aparté, si votre principale version ajoute des trucs à la documentation de l'supertype, vous pourriez être dans un monde de mal. J'ai étudié ce problème dans le cadre de mon Doctorat, et a constaté que, en général, les gens ne seront jamais au courant de l'information supplémentaire dans l'intérêt de la version si ils sont en invoquant par le biais d'un supertype.
D'aborder ce problème a été l'une des caractéristiques principales de l'outil prototype que j'ai construit - Chaque fois que vous avez appelé une méthode, vous avez obtenu une indication si sa cible ou de tout potentiel primordial objectifs contenus des informations importantes (par exemple, un comportement contradictoire de l'). Par exemple, lors de l'invocation de mettre sur une carte, il a été rappelé que si votre application est un TreeMap, vos éléments doivent être comparables.
La mise en œuvre et le fonctionnement de l'interface ont javadoc. Avec quelques outils, vous pouvez hériter de la documentation de l'interface avec le @inheritDoc mot-clé.
{@inheritDoc}et il ne fonctionne que si vous ne pas ont l'annotation@OverridepremièreUn peu de bonne pratique est de mettre
que la mise en œuvre de la javadoc (sauf si il y a quelque chose de supplémentaire pour être expliqué à propos de la mise en œuvre de détails).
Généralement, lorsque vous surcharger une méthode, vous adhérez au contrat défini dans la classe de base/interface, de sorte que vous ne souhaitez pas modifier l'original de la javadoc de toute façon. Par conséquent, l'utilisation de
@inheritDocou@seetag mentionné dans d'autres réponses n'est pas nécessaire et en fait ne sert que comme un bruit dans le code. Raisonnable outils hériter méthode javadoc de la classe mère ou de l'interface comme indiqué ici:Le fait que certains outils (je suis à la recherche à vous, Eclipse!) générer ces par défaut lors du remplacement d'une méthode n'est qu'un triste état de choses, mais cela ne justifie pas encombrer votre code inutile de bruit.
Il peut bien sûr être le cas contraire, lorsque vous souhaitez ajouter un commentaire à la méthode de remplacement (généralement de quelques autres détails de mise en œuvre ou de rendre le contrat un peu plus strictes). Mais dans ce cas, vous avez presque jamais l'envie de faire quelque chose comme ceci:
Pourquoi? En raison de l'héritage commentaire peut éventuellement être très long. Dans de tels cas, qui de l'avis de la phrase à la fin de la 3 longs paragraphes?? Au lieu de cela, il suffit d'écrire le morceau de votre propre commentaire et c'est tout. Tous les javadoc outils de toujours montrer une sorte de Spécifié par lien sur lequel vous cliquez pour lire la classe de base de commentaire. Il est inutile de les mélanger.
@voir qu'Il génère un lien vers la description de l'interface. Mais je pense qu'il est bon d'ajouter quelques détails au sujet de la mise en œuvre trop.
@seeles reliant à des méthodes d'interface est une bonne pratique, et il est suffisant dans la plupart des cas. Lorsque vous copiez javadoc de la méthode de l'interface pour la mise en œuvre concrète que vous venez de dupliquer l'information et il peut rapidement devenir incohérentes. Toutefois, des informations supplémentaires sur la mise en œuvre devrait être ajoutée à la javadoc.Sjoerd correctement dit que les deux d'interface et de mise en œuvre devrait avoir JavaDoc. L'interface JavaDoc doit définir le contrat de la méthode - ce que la méthode doit faire, quels sont les moyens qu'il faut, des valeurs qu'elle doit retourner, et ce qu'il doit faire en cas d'erreur.
La documentation de mise en œuvre devraient prendre note des extensions ou des restrictions sur le contrat, et aussi les détails de la mise en œuvre, en particulier de la performance.
Pour l'amour de généré javadoc oui il importe. Si vous déclarez des références à une mise en œuvre concrète à l'aide de l'interface alors ce n'est pas depuis l'interface de méthodes seront récupérées par l'IDE.