Commentaires sur la méthode surchargée en Java

Question

Devrions-nous commenter la méthode substituée ou non? Si oui, alors si le commentaire sera un document Java ou un simple commentaire?

Answer 1

@ La réponse de SimonC explique comment l'utilitaire javadoc génère une documentation «héritée» pour les méthodes surchargées.

Vous pouvez également placer des javadocs explicites dans une méthode de remplacement et ils auront la priorité sur les javadocs hérités. En outre, si vous placez la balise {@inheritDoc} dans les javadocs explicites de la méthode de substitution, les commentaires hérités seront inclus à ce stade.

Pour répondre à ceci:

Faut-il commenter la méthode surchargée ou non? Si oui, alors si le commentaire sera un document Java ou un simple commentaire?

À mon avis, si la méthode de substitution raffine la sémantique documentée (contrat) de la méthode surchargée (ou ... Dieu ne plaise ... brisera le contrat), cela mérite d'être documentée dans la méthode remplacement de javadocs. Cependant, si les différences sont simplement des «détails de mise en œuvre», alors des commentaires simples (ou aucun commentaire) sont plus appropriés.(Cependant, la pratique d'inclure un commentaire "non-javadoc" qui renvoie le lecteur au javadoc de la méthode surchargée est, IMO, une perte d'écran immobilier ... quand je lis le code source.

Answer 2

De How to Write Doc Comments for the Javadoc Tool:

réutilisation automatique de méthode comments

Vous pouvez éviter refrappe doc commentaires en étant conscient de la façon dont l'outil Javadoc doublons (hérite des paramètres) commentaires pour méthodes qui supplantent ou implémentent d'autres méthodes. Cela se produit dans trois cas: Lorsqu'une méthode dans une classe remplace une méthode dans un superclasse Lorsqu'une méthode dans une interface remplace une méthode dans un superinterface Lorsqu'une méthode dans une classe implémente une méthode dans une interface Dans la premier deux cas, si une méthode m() remplace une autre méthode, l'outil Javadoc va générer une sous-rubrique "Remplace" dans la documentation pour m(), avec un lien à la méthode qu'elle surcharge.

Dans le troisième cas, si une méthode m() dans une classe donnée implémente une méthode dans une interface, l'outil Javadoc générer une sous-position « spécifiée par » dans la documentation de m(), avec un lien vers la méthode qu'il implémente.

Dans les trois de ces cas, si l'outil commentaires ou balises méthode m() ne contient pas de doc, le Javadoc copiera également le texte de la méthode, il est primordial ou la mise en œuvre de la documentation générée pour m(). Donc si la documentation de la méthode implémentée substituée ou est suffisante, vous n'avez pas besoin d'ajouter la documentation pour m(). Si vous ajoutez un commentaire ou un tag à m(), le message "Remplace" ou "Spécifié par" sous-titre et le lien apparaîtra toujours, mais aucun texte ne sera copié .