Bonjour
J'aimerais savoir combien de commentaires vous mettez quand vous coder.
Mon prof d'informatique nous obligeait à mettre un commentaire par ligne de code et nous disait qu'on devrait être capable de recréer le code s'il ne restait plus que les commentaires.
C'est sûrement un peu exagéré, un commentaire tous les 5-6 lignes devraient suffire à mon avis.
En visionnant une partie des codes sources de certains programmes, je remarque qu'on est loin de ça. Je trouve que c'est quand même dommage, car plus de commentaires aiderait celui qui aimerait contribuer à un programme, créer un patch par exemple.
Forum Programmation.autre Commentaires dans le code
28
sept.
2008
# Alan Coxx ...
Posté par barmic . Évalué à 7.
Personnellement je commente comme voulu avec doxygène et je commente avant les blocs un peu complexes ou qui utilisent des subtilités du langage utilisés.
Voila je sais pas si ça peut t'aider.
Tous les contenus que j'écris ici sont sous licence CC0 (j'abandonne autant que possible mes droits d'auteur sur mes écrits)
# Pas de règle
Posté par Romeo . Évalué à 4.
Commenter un exit(0), n'a aucun interet et alourdi la lecture.
La plupart du temps commenter les variables n'a aussi pas d'interet, puisque le nom devrait refleter le role de la variable.
Je pense qu'une bonne manière de commenter et d'oublier le code derrière et commenter le but des fonctions (classes, ...) en terme plus générique.
# Séparation dans une fonction
Posté par Jean-François Martin . Évalué à 2.
J'applique surtout cette méthode dans les fonctions principal ( main en C ), pour séparer les différentes étapes de l'initialisation de mon programme.
int
main(int argc, char **argv) {
int blabla
....
....
/* Arguments-Options */
....
....
....
/* Configuration */
}
Normalement le code reste compréhensible sans les commentaires, mais leurs présence permettent de ce répérer et d'aller plus vite au bloc qui nous intéresse.
# theorie vs pratique
Posté par NeoX . Évalué à 4.
c'est la difference entre la theorie et la pratique.
pour ton prof, l'avantage de tes commentaires c'est que ca lui prouve que tu as compris qu'elle fonction fait quoi
genre avec le code et le commentaire suivant
//ce code ecrit hello world
#include fichier1
#include fichier2
void main(void)
{
printf("Hello World");
}
rien ne prouve que tu as compris ce qui fait l'ecriture et pourquoi...
alors que si tu commentes lignes à lignes, tu prouves que tu as compris pourquoi tu met les include, pourquoi include des ces fichiers...
etc etc
[^] # Re: theorie vs pratique
Posté par KiKouN . Évalué à 5.
[^] # Re: theorie vs pratique
Posté par Le Pnume . Évalué à 5.
# un seul dans le pire des cas
Posté par vincent LECOQ (site web personnel) . Évalué à 5.
mais en principe je preffere faire du code suffisement simple et decomposé en fonctions humainement lisibles qui peuvent se passer de commentaire.
faire une seule chose simple et la faire bien, un peu comme unix pour ses binaires.
# Commentaires indispensables
Posté par peck (site web personnel) . Évalué à 8.
- pour documenter une api publique (l'utilisateur ne lira pas le source -> doxygen ou équivalent)
- pour expliquer des astuces et des algorithmes (ex: "on utilise la technique des lapins roses, ... description ..." ou "il faut appeler cette fonction pour éviter un trou noir"
En dehors de ça, le code ça se lit comme l'anglais ou le chinois, il suffit de savoir lire (et que l'écrivain soit bon).
# ça dépend aussi du langage
Posté par santos . Évalué à 3.
Avec les langages modernes et orientés objet, avec une bonne sémantique métier, un architecture MVC, une implémentation judicieuse des modèles de conception classiques, etc... on arrive à faire du code qui demande peu de commentaires.
Comme évoqué précédemment, il faut surtout bien documenter les classes et les méthodes, et exposer un maximum de fonctionnalités de l'application sous forme d'API. De cette façon, ça oblige à concevoir l'application correctement, en faisant une bonne abstraction du langage, et en pensant soigneusement la couche métier.
Comme ça, avec simplement la documentation des méthodes et un bon document d'architecture, celui qui lit le code s'y retrouve.
Pour ne parler que du code lui-même (donc valable également en C, etc...), il faut attacher extrêmement d'importance à la sémantique des variables et des fonctions. Trop souvent on n'y fait pas attention, on met des noms de variable ésotériques (tmp_ceci, machin2, testCnx,...)
A moins de faire de l'embarqué ou autres domaines spécifiques, ça ne pèse pas lourd de mettre des noms de variables ou de fonctions explicites ! Pas d'abréviations, respect de la notation Camel ("maSuperFonctionQuiDéchire"), etc...
Enfin, en ce qui concerne les commentaires purs, en milieu de code, bien différencier les portions de code "métier", c'est à dire celles qui constituent le coeur de l'application, des portions de code "générique" (ex: ouverture et lecture d'un fichier, tri d'un tableau,...). Ces dernières portions, si elles sont proprement écrites, peuvent déjà être lues par un bon programmeur. Inutile de s'y attarder. En revanche, les portions de code métier doivent impérativement être commentées, même si elles sont triviales. Si ces portions ne sont pas commentées, essayer d'étudier l'application pour un développeur tiers revient à faire de la rétro-ingénierie sur ces portions ; le rôle des commentaires, c'est justement d'éviter cela.
Mais ne t'étonnes pas qu'en début de formation, on te demande de tout commenter. A ce niveau, ça revient à écrire l'algorithme, exprimer ce que tu as en tête au moment où tu codes. Au fil du temps, naturellement tu arrêteras de commenter ce qu'il n'est pas nécessaire de commenter.
[^] # Re: ça dépend aussi du langage
Posté par gaaaaaAab . Évalué à 1.
A ma gauche, les vieux langages comme le C, à ma droite .... les langages modernes + une bonne sémantique métier + une bonne architecture + une implémentation judicieuse ... c'est pas très équitable tout ça :-)
bon, là, je pense que tout le monde a compris que je fais du C toute la journée (et que j'aime ça en plus)
Revenons à nos moutons.
En réfléchissant sur les commentaires à l'occasion de ce sujet, je me rend compte que je ne les lis quasiment jamais. Plusieurs raisons à ça :
- quand le code est bien conçu et bien écrit, les commentaires sont quasi superflus,
- quand le code est mal écrit, les commentaires sont obsolètes ou hors sujet (bien que parfois hilarants).
Je n'ai besoin des commentaires que quand l'objectif poursuivi derrière un bloc de code n'est pas immédiatement compréhensible. Dans la pratique, c'est quand la logique métier vient imposer des contraintes arbitraires sur des éléments techniques ou quand l'architecture du soft fait que certaines écritures ésotériques sont privilégiées par rapport à une écriture plus classique.
Bref, c'est pas souvent.
Trust the source, Luke !
# Dans la vraie vie
Posté par bertrand . Évalué à 10.
Quand il y a des commentaires, ils sont au choix :
- triviaux (on m'a demandé de mettre des commentaires, je le fait),
- faux (/* vérifier que i est positif */ if (i == 0) ...);
- incompréhensible (j'ai déjà vu des commentaire en indhi ! (ben oui, je suis con je parle pas l'indhi couramment))
Des fois c'est les trois à la fois ! C'est d'ailleurs le cas du "vérifier que I est positif". Le commentaire ferait mieux d'expliquer le pourquoi du test plutôt que le détail ; genre "éviter une division par zéro".
Une certitude, les commentaires ne sont jamais maintenu. On est pressé la prod est plantée ! Ou bien le commercial a vendu ça pour hier et on est samedi, il est 23h00 !
Donc oui aux commentaires d'API, à l'explication de l'algo subtil etc.
Par contre et par pitié, épargnons nous les commentaire qui ne servent à rien si ce n'est à doubler le nombre de ligne à lire, puis à décider qui du commentaire ou du code à raison !
Par principe un code bien écrit doit être lisible. (bon en assembleur ça se complique)
Le prétexte genre "c'est du C donc je peux pas faire lisible" se traduit en "je suis pas bon, je ferai mieux de faire du cobol ça limitera les dégâts". (perso, je programme aussi en cobol, le moins souvent possible, soyons honnêtes :) )
J'espère n'avoir froissé personne.
# Moi même
Posté par Putifuto . Évalué à 4.
- Ce que doit faire la fonction
- Les paramêtres non triviaux,
- La valeur de retour.
- Et les conditions d'utilisations (base de données ouvertes, structures) pour que la fonction s'exécute bien.
Éventuellement, je rajoute les exceptions qui risquent d'être levées.
Commenter le code à l'intérieure de la fonction, c'est nul. Parce que :
1) lors de mise à jour du code, les commentaires n'ont pas d'obligation à être remis à jour. dans la réalité, ils ne le sont pas.
2) C'est le signe d'une mauvaise conception.
3) c'est chiant à faire.
voilà pour moi.
[^] # Re: Moi même
Posté par Axioplase ıɥs∀ (site web personnel) . Évalué à 3.
Avec tout de même des commentaires dans le corps des fonctions quand on se retrouve avec des manipulations obscures des données, genre
((call/cc ((lambda (x) (set! foo x) (bar x))) #\w))) ;; alloue 3 octets supplémentaires
Parfois même, je commente avec une version naive mais claire de l'algo.
# écrire de la documentation ne veut pas dire documenter le code source !
Posté par s[e]th & h[o]lth (site web personnel) . É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 !
# Commentaires
Posté par Maxime (site web personnel) . Évalué à 2.
Un jour, un bon programmeur m'a dit : "Un bon code propre n'a pas besoin de commentaire".
Si ce que tu fais est suffisamment clair, le langage en lui même est assez parlant.
D'ailleurs j'ai déjà perdu des points pour avoir mis trop de commentaires en partiel.
Dans la pratique, je met en début de chaque fonction (juste avant) son rôle et ses paramètres (syntaxe doxygen/javadoc). Le but étant de savoir ce que fait la fonction sans avoir à la relire.
Ensuite, je met des commentaires lorsqu'un bout de code n'est pas trivial.
Mais pour revenir sur ce que je disais au début, lorsque tu trouves que ton commentaire est inutile et que ton code est suffisamment clair sans, alors n'en met pas.
Je préfère lire un code peu commenté mais compréhensible qu'un code avec pleins de commentaires mais dont je ne comprend pas l'implémentation (ie avec des noms de variables pourris, mal découpé en fonctions, etc.)
# Perso, je n'en mets pas ou très peu ...
Posté par syj . Évalué à 1.
Pour moi un code bien propre, bien écrit doit se suffire à lui même.
Pour cela, je mets des nom de variables explicites.
- List listDuPersonnel;
- Iterator itDuPersonnel;
Les noms fonctions et de classes ont aussi des noms long et très explicite.
Enfin, dernier point le corps des fonctions restent toujours très court. Je découpe au maximum en sous-fonction pour éviter l'imbrication de while ,for et if dans une même fonction.
Enfin, je commente uniquement si le traitement est très complexe.
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.