Pour moi la bonne façon de commenter est de rédiger assez de documents afin d'éviter de commenter le code source car comme le disait un commentaire plus haut, un code robuste est un code lisible de lui-même !
Si le code a besoin de commentaire c'est sûrement que :
- soit le code est illisible => il faut décomplexifier le code
- soit le code est mal documenté => il faut commenter l'architecture globale, les différents modules ainsi que leurs rôles et leurs mise en oeuvre.
On peut toujours mettre 2/3 lignes de commentaires par-ci par-là mais le plus important est que le relecteur puisse savoir de quoi va parler telle ou telle classe/fichier/module avant d'ouvrir le fichier.
Il doit aussi savoir comment contruire et mettre des points d'arrêt dans le code. S'il s'agit d'une API, il faut fournir des exemples d'explications plus que de commenter chaque fonctions. Seules les fonctions "publiques" devraient avoir une explication claire et concise dans le code et celle-ci doit référer un document "humainement" lisible (une documentation word, pdf, html, etc...)
Ce n'est pas le code source que l'on doit commenter mais le projet global !
Si l'on considère les quatres libertés de la GPL comme source d'inspiration, je dirais que :
- pour avoir la possibilité d'exercer "La liberté d'exécuter le programme, pour tous les usages", il faut avoir assez de documentations permettant d'utiliser ce code => comment construire et executer celui-ci
- pour avoir la possibilité d'exercer "La liberté d'étudier le fonctionnement du programme, et de l'adapter à vos besoins" il faut avoir une documentation globale de l'architecture dans une large mesure et quelques commentaires dans le code référant à la documentation générale
- pour avoir la possibilité d'exercer "La liberté de redistribuer des copies, donc d'aider votre voisin" il faut documenter les changements que l'on a apporté à ce dernier et/ou adapter certaines parties de la documentation globale
- pour avoir la possibilité d'exercer "La liberté d'améliorer le programme et de publier vos améliorations, pour en faire profiter toute la communauté" il faut avoir une documentation sur les reglès à appliquer pour un développement commun et uniforme à savoir la liste des conventions de nommage, de programmation etc...
On se rend bien compte que la documentation du code source est parfois utile mais ne doit en aucun cas être LA partie importante de la documentation. Ce n'est que la partie immergée de l'iceberg !
# écrire de la documentation ne veut pas dire documenter le code source !
Posté par s[e]th & h[o]lth (site web personnel) . En réponse au message Commentaires dans le code. Évalué à 3.
Si le code a besoin de commentaire c'est sûrement que :
- soit le code est illisible => il faut décomplexifier le code
- soit le code est mal documenté => il faut commenter l'architecture globale, les différents modules ainsi que leurs rôles et leurs mise en oeuvre.
On peut toujours mettre 2/3 lignes de commentaires par-ci par-là mais le plus important est que le relecteur puisse savoir de quoi va parler telle ou telle classe/fichier/module avant d'ouvrir le fichier.
Il doit aussi savoir comment contruire et mettre des points d'arrêt dans le code. S'il s'agit d'une API, il faut fournir des exemples d'explications plus que de commenter chaque fonctions. Seules les fonctions "publiques" devraient avoir une explication claire et concise dans le code et celle-ci doit référer un document "humainement" lisible (une documentation word, pdf, html, etc...)
Ce n'est pas le code source que l'on doit commenter mais le projet global !
Si l'on considère les quatres libertés de la GPL comme source d'inspiration, je dirais que :
- pour avoir la possibilité d'exercer "La liberté d'exécuter le programme, pour tous les usages", il faut avoir assez de documentations permettant d'utiliser ce code => comment construire et executer celui-ci
- pour avoir la possibilité d'exercer "La liberté d'étudier le fonctionnement du programme, et de l'adapter à vos besoins" il faut avoir une documentation globale de l'architecture dans une large mesure et quelques commentaires dans le code référant à la documentation générale
- pour avoir la possibilité d'exercer "La liberté de redistribuer des copies, donc d'aider votre voisin" il faut documenter les changements que l'on a apporté à ce dernier et/ou adapter certaines parties de la documentation globale
- pour avoir la possibilité d'exercer "La liberté d'améliorer le programme et de publier vos améliorations, pour en faire profiter toute la communauté" il faut avoir une documentation sur les reglès à appliquer pour un développement commun et uniforme à savoir la liste des conventions de nommage, de programmation etc...
On se rend bien compte que la documentation du code source est parfois utile mais ne doit en aucun cas être LA partie importante de la documentation. Ce n'est que la partie immergée de l'iceberg !