Meilleures pratiques dans la rédaction de commentaires et la documentation
Commentaire de nos jours est plus facile que jamais. En Java, il existe de belles techniques pour relier les commentaires aux classes, et Java IDes sont bons pour faire des coquillages de commentaire pour vous. Des langues comme Clojure vous permettent même d'ajouter une description d'une fonction dans le Code de fonction elle-même comme argument.
Cependant, nous vivons toujours à une époque où il y a souvent des observations obsolètes ou médiocres écrites 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 à la langue.
Existe-t-il des techniques émergentes qui valident des commentaires et détectent automatiquement les commentaires "fragiles" (par exemple, des commentaires avec des numéros magiques, des phrases incomplètes, etc.) ou des commentaires incorrects (par exemple, la détection de variables malpulsées ou similaires).
Et plus important encore: existe-t-il accepté des "politiques de commentaire" ou des stratégies là-bas? Il y a beaucoup d'avis sur la manière de coder - mais qu'en est-il de "Comment commenter?"
Les noms/la documentation devraient vous dire quoi 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.
Cela pourrait être controversé, mais mon conseil serait d'écrire autant de commentaires que possible. Utilisez des noms de classe Nice, clairs, noms de variables et noms de méthodes. Écrivez votre code de la manière la plus claire que vous puissiez; Et considérez ceci comme l'attribut le plus important de votre code (autre que celui qui répond à ses exigences). Écrivez un commentaire uniquement si vous avez fait une méthode aussi claire que vous le pouvez, et vous pensez toujours que cela nécessite une explication plus approfondie.
Et avoir une pratique organisationnelle, que chaque fois que quiconque change une classe de quelque manière que ce soit, ils doivent s'assurer que les commentaires sont toujours corrects.
Je ne suis pas sûr d'autres langues, mais python vous permet d'écrire doctests qui sont une forme de commentaires auto-validant. Bien sûr, ils ne devraient pas être utilisé à la place de tests d'unités réelles, mais constitue une méthode rapide et facile de documenter des fonctions spécifiques qui peuvent ne pas être aussi évidentes qu'elles devraient être aussi évidentes qu'elles soient. Ils sont accompagnés de l'avantage supplémentaire de pouvoir exécuter les tests de commentaire pour vérifier que les commentaires sont toujours correct (au moins la partie d'entre eux contenant des tests).
L'un des emplacements les plus autorisés à trouver Comment utiliser le code commentaire pour générer automatiquement la documentation est sûrement DOXYGEN . Bien qu'il puisse moi plus de ces outils.
Cela définit la norme de la rédaction de commentaires qui devrait être suivie pour générer automatiquement une documentation. Cependant, cela donne plus d'une structure mais ne valident pas sémantiquement; Par exemple, il ne peut pas vérifier si vous avez utilisé des anglophones trompeurs pour décrire le but d'une fonction!
Bien que c'est la meilleure chose qui rend les commentaires structurés, je pense que vous avez plus de documentation nécessaire pour rendre le code plus maintenu en tant que tel. Un peu de temps, il y avait une question dans P.SE CO CODE Soyez la documentation dans des outils de développeurs open source? Quelle est la fréquence? Bien sûr, cela s'applique également aux projets non open-source.
Pour rendre le code plus maintenu - il est pratiquement plus important qu'il existe une documentation externe qui aide à créer une structure de la manière de traiter le code, puis des commentaires à l'intérieur du code doivent être limités à voir
Je pense que si vous souhaitez définir les stratégies pour commentaires écrit Vous devez inclure comme une approche holistique incluse dans la norme de codage. Voir ceci: Quels peuvent être des pièges à introduire un guide de style et une documentation générant des logiciels dans une équipe de développement?
Habituellement, un commentaire représente moins de 5% du code. Et en pratique, tandis que les examens du code soient attirés beaucoup moins d'attentions (sur d'autres aspects du développement) sont pratiquement difficiles que des commentaires sont également examinés.
Existe-t-il des techniques émergentes qui valident des commentaires et détectent automatiquement les commentaires "fragiles" (par exemple, des commentaires avec des numéros magiques, des phrases incomplètes, etc.) ou des commentaires incorrects (par exemple, la détection de variables malpulsées ou similaires).
Il y a une technique bien connue - elle s'appelle "examen de code" et a une soeur nommée "Pair-programmation". Ne vous attendez pas à quelque chose de "automatiquement" ici.
Et plus important encore: existe-t-il accepté des "politiques de commentaire" ou des stratégies là-bas? Il y a beaucoup d'avis sur la manière de coder ---, mais qu'en est-il de "Comment commenter?"
"Code complet" contient non seulement tout sur la manière de coder, mais également des chapitres sur "Comment commenter", surtout sur la façon d'écrire un code auto-documentant.
Spécifique à Java Une source que j'ai appréciée est Oracle Comment écrire des commentaires doc pour l'outil Javadoc :
Ce document décrit le guide de style, la balise et les conventions d'image que nous utilisons dans les commentaires de la documentation pour Java programmes écrites à Java logiciel, 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 a été générée manuellement et la maintien de la synchronisation avec le code était une corvée. Le Java Environnement de programmation facilite cette tâche avec l'utilitaire Javadoc. Javadoc génère une documentation API automatiquement à partir du code source avec des commentaires spécialement formatés de documentation, plus communément appelé commentaires doc.