Je veux écrire Javadoc de manière SECHE. Mais le document Oracle sur Javadoc dit à nouveau d'écrire la même chose dans le commentaire de la méthode de surcharge. Puis-je éviter la répétition?
Je veux écrire Javadoc de manière SECHE. Mais le document Oracle sur Javadoc dit à nouveau d'écrire la même chose dans le commentaire de la méthode de surcharge. Puis-je éviter la répétition?
Réponses:
Je saupoudre des {@inheritDoc}directives ici et là dans mes commentaires Javadoc lors de la substitution de méthodes à partir de superclasses ou de l'implémentation de méthodes définies par l'interface.
Cela fonctionne bien pour moi au moins, évite la répétition dans le code source, et vous pouvez toujours ajouter des informations spécifiques au commentaire Javadoc particulier si cela est nécessaire. Je ne considère pas le fait que le commentaire Javadoc lui-même est assez nu pour être un problème quand tout ce qu'il faut dans un IDE décent est de survoler le nom de l'identifiant associé pour obtenir le Javadoc rendu avec des références et tout.
Le point de la documentation est d'éclairer les futurs utilisateurs d'un article. C'est en partie pour la commodité de l'auteur, afin qu'il ou elle ne doive pas être contacté chaque fois que quelqu'un ne peut pas comprendre comment la chose fonctionne. Cependant, la plupart du temps, c'est pour le bénéfice des personnes qui ont besoin d'utiliser ou de soutenir la chose.
En tant que tel, le point devrait être la clarté, par opposition à la commodité pour l'auteur. Vous ne pouvez pas vous attendre à ce que les gens parcourent la documentation de votre API, car vous étiez essentiellement trop paresseux pour vous répéter. Suck it up - Javadoc sera répétitif.
Cela dit, il n'y a aucune raison, si vous êtes intelligent, vous ne pouvez pas écrire un programme qui collerait des commentaires dans votre code en fonction de marqueurs ou d'autres critères. Cela peut être plus difficile que ça en vaut la peine. Ou pas.