Code auto-documenté vs Javadocs?

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?

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.

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.

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.

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.

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.

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)