Devrait commentaires JavaDoc être ajouté à la mise en œuvre

Question

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 non commentaires JavaDoc pour les implémentations lorsque vous générer automatiquement des commentaires. Ne pas le béton méthode la description?

Answer 1

Pour les méthodes qui sont seulement la mise en œuvre (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. Utiliser @Inheritdoc ou 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.

S'attaquer à 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.

Answer 2

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
 *
 * This implementation is very, very slow when b equals 3.
 */
public foo(int b)
{ ... }

Answer 3

Un peu de bonne pratique est de mettre

/**
 * {@inheritDoc}
 */

comme 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).

Answer 4

@voir 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.

Answer 5

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.