Meilleures pratiques en matière de rédaction de commentaires et de documentation

20

Aujourd'hui, commenter est plus facile que jamais. En Java, il existe de belles techniques pour lier les commentaires aux classes, et les IDE Java sont bons pour créer des shells de commentaires pour vous. Des langages comme Clojure vous permettent même d'ajouter une description d'une fonction dans le code de fonction lui-même comme argument.

Cependant, nous vivons toujours à une époque où il y a souvent des commentaires obsolètes ou pauvres écrits par de bons développeurs - je suis intéressé à améliorer la robustesse et l'utilité de mes commentaires.

En particulier, je suis intéressé par Java / Clojure / Python ici, mais les réponses n'ont pas besoin d'être spécifiques au langage.

Existe-t-il des techniques émergentes qui valident les commentaires et détectent automatiquement les commentaires "fragiles" (par exemple les commentaires avec des nombres magiques, les phrases incomplètes, etc.) ou les commentaires incorrects (par exemple, la détection de variables mal orthographiées ou similaires).

Et plus important encore: existe-t-il des «politiques de commentaires» ou des stratégies acceptées? Il existe de nombreux conseils sur la façon de coder - mais qu'en est-il de "commenter?"

java python clojure comments jayunit100
la source

Réponses:

40

  • Les noms / documentation devraient vous dire ce que vous faites.

  • La mise en œuvre devrait vous dire comment vous le faites.

  • Les commentaires devraient vous dire pourquoi vous le faites comme vous le faites.

monstre à cliquet
la source
6
les commentaires devraient également vous expliquer pourquoi vous ne le faites pas d' une autre manière - c'est-à-dire des choix de conception importants - car les futurs responsables n'auront pas ces informations autrement.
2
Je crois qu'il y a plusieurs fois un commentaire qui devrait dire CE QUE vous faites aussi. Cette idée de seulement "pourquoi" des commentaires est un anti-modèle à mon avis. C'est un mythe que vous pouvez écrire tout le code suffisamment clair pour que tout programmeur puisse le comprendre en un coup d'œil, et mon expérience est que la plupart des programmeurs qui pensent qu'ils écrivent du code propre ne le font pas. C'est la même chose que de dire: «Je n'ai pas à nommer cette fonction de manière descriptive, car n'importe qui peut simplement lire le code de la fonction pour voir ce qu'elle fait. - ça n'a pas de sens non plus, non?
dallin
2
@dallin si votre code n'est pas clair sur ce qu'il fait; envisager de le refactoriser. Sinon, ajoutez un commentaire expliquant pourquoi il est implémenté comme ça (ce qui explique également comment mieux). Votre comparaison avec des noms descriptifs est des pommes / oranges, un nom descriptif indique clairement où la fonction est utilisée et vous n'avez peut-être pas accès au code source de la fonction.
Ratchet Freak
@dallin: "C'est un mythe que vous pouvez écrire tout le code suffisamment clair pour que tout programmeur puisse le comprendre en un coup d'œil", oncle Bob voudrait avoir un mot avec vous. - "Je n'ai pas besoin de nommer cette fonction de manière descriptive car n'importe qui peut simplement lire le code dans la fonction pour voir ce qu'elle fait." fait!
klaar
14

Cela pourrait être controversé, mais mon conseil serait d'écrire le moins de commentaires possible. Utilisez plutôt des noms de classe, des noms de variables et des noms de méthode clairs et agréables. Écrivez votre code de la manière la plus claire possible; et considérez qu'il s'agit de l'attribut le plus important de votre code (à part qu'il répond à ses exigences). N'écrivez un commentaire que si vous avez rendu une méthode aussi claire que possible, et que vous pensez toujours qu'elle nécessite des explications supplémentaires.

Et avoir une pratique organisationnelle, que chaque fois que quelqu'un change une classe de quelque manière, il doit s'assurer que les commentaires sont toujours corrects.

Dawood dit réintégrer Monica
la source
1
C'est un bon début, mais je pense que pour répondre à la question du PO, vous devrez écrire quelque chose qui répond à ses véritables préoccupations concernant la validation automatique.
Robert Harvey
2
+1 - Je pense également que les commentaires ne doivent être utilisés que pour expliquer pourquoi du code a été écrit. Je sais ce que if (a == b) then c();ça fait, mais si je ne sais pas pourquoi il le fait - c'est alors qu'un commentaire devrait être utilisé :)
Deco
Déco - je suis complètement d'accord. Les commentaires sont bons lorsque je veux comprendre comment une méthode particulière s’inscrit dans le processus dans son ensemble. En d'autres termes, POURQUOI vous appelleriez cette méthode, ou POURQUOI elle fait ce qu'elle fait.
Dawood dit de réintégrer Monica
En plus de rendre le code écrit clair, nous devons également nous assurer de conserver (au niveau du code) les idées, les pensées, etc. en utilisant les commentaires TODO. Par exemple, si vous voyez qu'une fonction / classe est capable de gérer correctement la taille actuelle des données, mais ne parviendra pas à gérer la charge après 2 ans, assurez-vous d'écrire votre observation à l'aide du commentaire TODO. Les futurs développeurs apprécieront en effet vos efforts. N'essayez jamais de noter ces choses dans un document txt / word séparé, lors de l'écriture de code, personne ne fait vraiment référence à de tels documents.
TechCoze
voir aussi: «Les commentaires sont une odeur de code»
gnat
5

Je ne suis pas sûr des autres langages, mais python vous permet d'écrire des doctests qui sont une forme de commentaires d'auto-validation. Bien sûr, ils ne doivent pas être utilisés à la place de tests unitaires réels, mais constituent une méthode rapide et facile de documenter des fonctions spécifiques qui peuvent ne pas être aussi évidentes qu'elles devraient l'être. Ils ont l'avantage supplémentaire de pouvoir exécuter les tests de commentaire pour vérifier que les commentaires sont toujours corrects (au moins la partie d'entre eux qui contient des tests).

Josh Smeaton
la source
1
Et Sphinx compare le code à la documentation pour fournir des mesures de couverture.
S.Lott
3

L'un des emplacements les plus fiables pour trouver comment utiliser le commentaire de code pour générer automatiquement de la documentation est sûrement doxygen . Bien qu'il puisse y avoir plus d'outils de ce type.

Cela définit la norme d' écriture des commentaires qui doit être suivie pour générer automatiquement la documentation. Cependant, cela donne plus d'une structure mais ne valide pas sémantiquement; par exemple, il ne peut pas vérifier si vous avez utilisé un anglais trompeur pour décrire le but d'une fonction!

Bien que ce soit la meilleure chose pour structurer les commentaires, personnellement, je pense qu'il y a plus de documentation nécessaire pour rendre le code plus maintenable en tant que tel. Il y a quelque temps, il y avait une question dans P.SE Le code peut-il être la documentation des outils de développement open source? Quelle est sa fréquence? Bien sûr, cela s'applique également aux projets non open-source.

Pour rendre le code plus facile à gérer - il est pratiquement plus important qu'il existe une documentation externe qui aide à créer une structure sur la façon de traiter le code, puis les commentaires à l'intérieur du code doivent être limités pour voir

Je pense que si vous voulez définir les politiques de rédaction des commentaires, vous devez inclure une approche holistique incluse dans la norme de codage. Voir ceci: Quels pourraient être les pièges dans l'introduction d'un guide de style et d'un logiciel de génération de documentation dans une équipe de développement?

Habituellement, un commentaire constitue moins de 5% du code. Et dans la pratique, alors que les révisions de code elles-mêmes attirent beaucoup moins d'attention (sur d'autres aspects du développement), il est pratiquement difficile que les commentaires soient également examinés.

Dipan Mehta
la source
1
Je ne suis pas d'accord avec la dernière phrase ici. Je viens de terminer un contrat, travaillant sous la direction d'un chef d'équipe qui a donné des avis très détaillés. Ses critiques incluaient toujours les commentaires - comment ils étaient libellés, si les noms des variables étaient corrects, s'ils contenaient toutes les informations qu'un futur développeur pourrait vouloir savoir. Avant longtemps, je savais ce qu'il s'attendait à voir dans chaque commentaire, et j'ai pu produire des commentaires à son niveau. Donc, à condition que la politique organisationnelle prévoie des révisions de code et inclue des commentaires dans la révision de code, cela se produira.
Dawood dit de réintégrer Monica
C'est généralement le seul type de commentaire que j'écris, en particulier pour les méthodes permettant de documenter ce qui entre et ce qui en sort (je travaille avec des langages peu typés).
DanMan
2

Existe-t-il des techniques émergentes qui valident les commentaires et détectent automatiquement les commentaires "fragiles" (par exemple les commentaires avec des nombres magiques, les phrases incomplètes, etc.) ou les commentaires incorrects (par exemple, la détection de variables mal orthographiées ou similaires).

Il existe une technique bien connue - elle est appelée "révision de code" et a une sœur nommée "programmation par paires". Ne vous attendez à rien "automagiquement" ici.

Et plus important encore: existe-t-il des «politiques de commentaires» ou des stratégies acceptées? Il existe de nombreux conseils sur la façon de coder --- mais qu'en est-il de "commenter?"

"Code complet" contient non seulement tout sur la façon de coder, mais aussi des chapitres sur "comment commenter", en particulier sur la façon d'écrire du code auto-documenté.

Doc Brown
la source
+1 pour Code complet. Clean Code de Robert Martin contient également un bon chapitre sur la rédaction de recommandations utiles. Je ne suis pas sûr du monde Java mais dans le monde .NET, nous avons Resharper, qui peut valider "automatiquement" les références aux éléments de code dans les commentaires :)
MattDavey
0

Spécifique à Java, une source que j'ai appréciée est Comment écrire des commentaires de doc pour l'outil Javadoc d' Oracle :

Ce document décrit le guide de style, les balises et les conventions d'image que nous utilisons dans les commentaires de documentation pour les programmes Java écrits par Java Software, Sun Microsystems.

Et point 44: écrire des commentaires de doc pour tous les éléments d'API exposés :

Si une API doit être utilisable, elle doit être documentée. Traditionnellement, la documentation de l'API était générée manuellement et la synchroniser avec le code était une corvée. L'environnement de programmation Java facilite cette tâche avec l'utilitaire Javadoc. Javadoc génère automatiquement la documentation de l'API à partir du code source avec des commentaires de documentation spécialement formatés, plus communément appelés commentaires de doc.

de Effective Java 2nd Edition .

EGHM
la source