Code auto-documenté vs Javadocs?


18

Récemment, j'ai travaillé sur la refactorisation de parties de la base de code que je traite actuellement - non seulement pour mieux le comprendre moi-même, mais aussi pour le rendre plus facile pour les autres qui travaillent sur le code.

J'ai tendance à me pencher du côté de penser que le code auto-documenté est agréable . Je pense juste que c'est plus propre et si le code parle de lui-même, eh bien ... C'est super .

D'autre part, nous avons une documentation telle que javadocs. J'aime aussi cela, mais il y a un certain risque que les commentaires ici deviennent obsolètes (ainsi que les commentaires en général bien sûr). Cependant, s'ils sont à jour, ils peuvent être extrêmement utiles, par exemple pour comprendre un algorithme complexe.

Quelles sont les meilleures pratiques pour cela? Où tracez-vous la frontière entre le code auto-documenté et les javadocs?

Réponses:


24

Le code auto-documenté (et les commentaires dans le code) et les commentaires Javadoc ont deux publics cibles très différents.

Le code et les commentaires qui restent dans le fichier de code sont destinés aux développeurs. Vous voulez répondre à leurs préoccupations ici - faites en sorte qu'il soit facile de comprendre ce que fait le code et pourquoi le code est tel qu'il est. L'utilisation de noms de variables appropriés, de méthodes, de classes, etc. (code auto-documenté) couplée à des commentaires permet d'y parvenir.

Les commentaires Javadoc sont généralement destinés aux utilisateurs de l'API. Ce sont également des développeurs, mais ils ne se soucient pas de la structure interne du système, seulement des classes, des méthodes, des entrées et des sorties du système. Le code est contenu dans une boîte noire. Ces commentaires doivent être utilisés pour expliquer comment effectuer certaines tâches, quels sont les résultats attendus des opérations, quand des exceptions sont levées et ce que signifient les valeurs d'entrée. Étant donné un ensemble de documentation généré par Javadoc, je devrais être en mesure de comprendre pleinement comment utiliser vos interfaces sans jamais regarder une ligne de votre code.


+1, c'est un bon appel. Je pense que ma principale prise en main est que je ne le vois pas comme deux publics cibles différents, mais vous avez raison.
Andreas Johansson

1
@Andiaz - Je trouve utile de différencier les bords extérieurs du système (comme une API de service) et les classes à l'intérieur. Je travaille souvent sur des projets où la convention consiste à utiliser javadoc toutes les méthodes publiques, mais je prends beaucoup plus de soin sur les classes externes pour donner une indication de la façon dont la classe (et le système) devraient être utilisés. Sur les classes internes, je suppose que le lecteur a plus de connaissances sur le domaine et minimise le javadoc, laissant les noms de méthode parler plus d'eux-mêmes.
Steve Jackson

3
@SteveJackson Je suis d'accord, cependant, je me suis retrouvé à utiliser plus de Javadocs (même sur des membres privés) depuis que les IDE (au moins Eclipse et NetBeans) affichent les commentaires Javadoc dans les info-bulles de complétion de code. Bien sûr, ils ne sont pas aussi propres que les interfaces publiques, ils fournissent des conseils / notes à d'autres développeurs.
Thomas Owens

24

Le code dit comment . Les commentaires disent pourquoi , et peut-être même pourquoi pas .

C'est votre travail de fournir aux futurs lecteurs et mainteneurs de votre code. Mettez tout ce que vous pouvez dans le code et le reste dans les commentaires.

Notez que les choses les plus difficiles à saisir sont les décisions de conception - souvenez-vous-en aussi.


2
+1: Ce n'est pas "soit-ou" dans un sens exclusif. C'est à la fois dans un sens inclusif.
S.Lott

Je suis définitivement d'accord avec ça. Y a-t-il autre chose que vous envisageriez en ce qui concerne les javadocs en particulier? Comme, je peux imaginer que décrire ce qu'une méthode fait pourrait être utile, par exemple, pour les API.
Andreas Johansson

Les Javadocs sont très facilement accessibles depuis la plupart des IDE. Facilitez la navigation vers de plus amples informations.

+1: Les meilleurs commentaires que j'ai vus ont inclus des références aux articles où les algorithmes utilisés ont été discutés en profondeur; ce n'est pas quelque chose qui peut être auto-documenté dans les noms de variable / méthode, et n'appartient pas nécessairement dans doc-comments car l'algorithme fait partie de l' implémentation et non de l' interface .
Donal Fellows

4

L'utilisation de Javadocs ne fait pas vraiment de différence - puisque les documents générés contiennent le nom de vos fonctions avec le texte des commentaires, il n'y a absolument aucune raison pour que vous répétiez quoi que ce soit dans les commentaires qui soit clair par le nom de la fonction elle-même.

Si, d'autre part, vous avez une fonction où il faut d'abord regarder l'implémentation pour comprendre à quoi elle sert (donc ne pas mettre ces informations à la disposition de Javadocs), alors le code est à mon humble avis pas auto-documenté, peu importe la clarté de la mise en œuvre.


3
+1 mon préféré est lorsque la norme de code d'entreprise nécessite des méthodes documentées, mais tout le monde utilise un générateur qui répète simplement ce que le code dit déjà. Ennuyeux et inutile.
Kryptic

1

Je pense qu'avec javadocs, les choses sont les mêmes qu'avec n'importe quelle documentation - la règle principale est:

suivre le public

Est - ce que beaucoup de gens lisent vos javadocs? Si oui, il est logique d'investir des efforts pour bien faire les choses.

Vos lecteurs ont-ils tendance à ignorer la lecture du code au profit de l'étude des javadocs? Si oui, il est deux fois plus judicieux de consacrer des efforts à bien l'écrire.

  • C'est exactement le cas avec la documentation JDK . Devinez Sun / Oracle a consacré beaucoup d'efforts à ces derniers et ils semblent avoir un bon retour sur investissement dans les documents API largement utilisés par la communauté.

Maintenant, est-ce votre cas? Sinon, réfléchissez bien si les efforts investis dans les javadocs sont justifiés.

Comme déjà indiqué ci-dessus, écoutez le public pour découvrir le chemin.

  • Si vous entendez des plaintes actives concernant une documentation insuffisante, envisagez d'investir pour l'améliorer.
     
    Si, d'un autre côté, tout ce que vous entendez, c'est que les développeurs se plaignent des règles braindead les obligeant à perdre du temps sur une frappe inutile, alors il y a de fortes chances que vos efforts javadocs soient comme investir dans des prêts hypothécaires à risque . Pensez plutôt à de meilleurs investissements.

0

Je veux juste commenter la crainte que les commentaires Javadoc ne deviennent obsolètes. Bien que @JonathanMerlet ait raison de dire que le Javadoc doit être stable, vous pouvez également aider en examinant le Javadoc et les commentaires ainsi que le code lors de l'examen par les pairs. Les commentaires correspondent-ils à ce que fait le code? Sinon, ce qui est incorrect, et insistez pour que le développeur le répare. Essayez d'encourager d'autres développeurs à faire de même. Cela permet de maintenir à jour non seulement la documentation externe (commentaires Javadoc), mais également tous les commentaires de code réguliers. Cela aide les développeurs qui viennent après votre refactoring à comprendre le code plus rapidement et facilement, et rend sa maintenance beaucoup plus simple à l'avenir.


-1

Je pense que javadocs est approprié pour les parties qui doivent rester stables (API) afin que le risque de dépassement des commentaires soit minimisé, tandis que le code auto-documenté est idéal pour ce qui est sujet à des changements fréquents (implémentation). Bien sûr, les API peuvent changer au cours du projet, mais ayant l'en-tête juste avant la déclaration, les synchroniser n'est pas si difficile (par rapport à un commentaire sur plusieurs lignes expliquant plusieurs lignes de code)

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.