Un code bien écrit a-t-il besoin des commentaires ?

Il est des fois nécessaire d'écrire du code un peu complexe. Calculs mathématique, utilisation d'API obscures, rappel pour du code à ajouter ou à améliorer. De plus on n'a pas tous le même cerveau (heureusement :mrgreen:), on ne pense pas tous pareil.
Je ne sais pas trop pour les autres langages, mais en Delphi j'utilisais assez la balise { TODO 1 -uILP -cBase de données: Connexion à revoir } pour me souvenir d'un jour à l'autre, où j'en suis arrivé. Tout est alors rassemblé dans la fenêtre "À faire".
Personnellement, j'ai tendance à trop commenter. Une action, un commentaire. Mais j'ai toujours trouvé que c'était plus facile pour me retrouver dans mon propre code 8-).
Et ceci en plus de nommer mes méthodes et variables de façon clair.

Si j'ai bien compris, le bonhomme nous explique qu'un commentaire non pertinent n'est pas pertinent, et qu'un commentaire pertinent est pertinent.

Sans commentaire.

Les commentaires, c'est comme l'éclairage sur l'autoroute. Ce n'est pas indispensable, mais ça aide.

Citation:

---

Envoyé par nouknouk

Si j'ai bien compris, le bonhomme nous explique qu'un commentaire non pertinent n'est pas pertinent, et qu'un commentaire pertinent est pertinent.
Sans commentaire.

---

Je pense plutôt que le "bonhomme" cherche à montrer que tout les commentaires ne sont pas pertinents. Accessoirement il montre quels commentaires sont pertinents et lesquels ne le sont pas.
Quand je vois les codes/commentaires sur lesquels je tombe, j'ai envie de lui dire merci !
Bon, de mon coté j'ai tendance à ne commenter à l'intérieur des méthodes que quand la situation l’exige (algo complexe). Je ne commente les méthodes/classes seulement si elles ont vocation à être utilisées en tant qu'API ou éventuellement en attendant de trouver un nom/découpage clair (avec un TODO). Je ne vais pas perdre mon temps à ajouter des @param et autres, quand la seule lecture du nom du paramètre/méthode suffit.

Je suis de plus en plus pour un code sans commentaires. Ceux ci n'ont aucune valeur pour le compilateur, et du coup sont potentiellement erronés.

Je ne compte plus les commentaires effacés dans le code sur lequel je travaille, parce qu'ils deviennent tous obsolètes trop vite, ou bien simplement incompréhensibles, ... et pire encore, ils nous induisent souvent en erreur après un certain temps.

Je ne suis pas du tout d'accord.

Premièrement (et ça a déjà été dit), les commentaires aident quelqu'un qui reprendrait le code à le comprendre plus facilement. A part dans un HelloWorld, les noms de variables et de méthodes ne peuvent pas être assez explicites pour se passer de commentaires. Donc, au minimum, les déclarations de variables et les entêtes de méthodes doivent être commentées.

Ensuite, concernant le commentaire dans le corps des fonctions, ils aident autant celui qui écrit le code que celui qui le reprendra un jour. C'est vrai surtout s'il s'agit d'algorithme un peu compliqué. Avant d'écrire un code compliqué, je réfléchi à l'algo, et j'écris les principales étapes de l'algo sous forme de commentaire dans le corps de ma méthode. Une fois que c'est fait, je n'ai plus besoin de réfléchir: il ne reste qu'à remplir le code entre les commentaires.

J'ai donc un raisonnement inverse à celui de cet article: pour moi, une méthode bien commentée doit pouvoir se comprendre en lisant uniquement les commentaires; on ne comprendra pas comment le code fait, mais on saura parfaitement ce qu'il fait.

Je suis d'accord avec l'article dans le sens qu'un commentaire n'est pas une paraphrase du code( cf la partie extrait(), load() etc ..)
Par contre, en relisant du code, combien ai-je pu râler ou perdu de temps à comprendre le POURQUOI et non le COMMENT.
J'aurais préféré dans le code parfois un commentaire qui explique un choix d'un algorithme ou d'une implémentation comme, par exemple en java, une ArrayList au lieu d'une LinkedList ( et y'en a d'autre; cet exemple n'est pas à prendre au pied de la lettre)
J'ai pu constater aussi qu'en absence d'explication sur le pourquoi, on se retrouve avec du code dit "historique" avec lequel personne ne veux prendre de décision. Parfois aussi ne comprenant pas les raisons à l'époque de l'implémentation, on casse un code qui fonctionne pour des raisons bien particulières.
Un commentaire devrait aussi indiquer des numéro de bug pour des fix.
En conclusion, des commentaires, oui, mais qui explique le pourquoi. Encore faut il que le développeur joue le jeu : l'information n'est elle pas une source de pouvoir ?

Trop simple.
1. Commente-t-on uniquement un code parce qu'on pense qu'il faut "toujours" commenter un code ?

Commente-t-on un code pour pouvoir le relire ou pour permettre aux autres de le relire ? Et la question corolaire :
Supprime-t-on les commentaires d'un code pour le protéger contre la relecture par des yeux indélicats ?
Quid des obfuscateurs ?
Quid des noms de variables "auto-documentées" qui occupent 40 caractères à force de leur ajouter des préfixes et des suffixes alors que ladite variable s'appelle déjà "RésultatBoucleAprèsSuppressionDesDoublons"
Pourquoi utilise-t-on des acronymes comme EOF, CRLF, ASCII ? Doit-on se limiter aux acronymes historiques ou peut-on en créer de nouveaux en fonction des notions manipulées par le programme et dans ce cas, où peut-on documenter ces nouveaux acronymes ?

autres considérations :
Dois-je commenter du javascript ? Doisje mettre des noms de variables explicites en javascript ?
Pire :
Quand je fais un portage entre du php et du C# , dois-je modifier les noms de variables puisque l'un est précompilé et l'autre non ?

Difficile alors de donner une opinion expéditive sur cette question. Un beau code est à la fois facile à lire et légèrement commenté il me semble. Pour l'éducation, les commentaires mettront l'accent sur les points étudiés.
En production dans une grande équipe , on commente pour des professionnels supposés formés.. En solitaire free-lance on évite de produire un code trop facile à lire car on craint qu'un développeur peu expérimenté jouissant de tous les droits chez le client vienne modifier le code et y introduire des bugs de débutant aussi ....

Tout cela me fait penser que les situations peuvent être très différentes et que les personnes qui lisent votre code ne sont pas nécéssairement bien inspirées à l'égard de votre travail . Bien entendu, le contraire est non seulement possible mais hautement souhaitable et un développeur trop parano risque de s'attirer des remarques désobligeantes qui justifieront sa future parano et ainsi de suite..

Ensuite , il y a ces languages très optimisables comme le C où on peut recourir à des syntaxes absolument illisibles pour des raisons de performance (liste chainée de pointeurs sur pointeurs sur fonctions...)

Est ce que cette page est uniquement réservée à des étudiants ou des gens qui ne jurent que par le code ouvert ?

Finalement , si vous etes en confiance et que les gens qui vous entourent méritent cette confiance , commentez régulièrement car , on peut parcourir le code uniquement en lisant les commentaires pour s'arréter exactement là où on a une modif à faire - modif qui sera datée et signée dans un commentaire ...

Citation:

---

Envoyé par barmic

(.../...)
Le code répond à la question : « Comment ? »
Les commentaires répondes à la question : « Pourquoi ? »

---

+1

Citation:

---

Envoyé par jiber2fr

(.../...)
J'ai donc un raisonnement inverse à celui de cet article: pour moi, une méthode bien commentée doit pouvoir se comprendre en lisant uniquement les commentaires; on ne comprendra pas comment le code fait, mais on saura parfaitement ce qu'il fait.

---

En fait, les deux. Je suis sans doute extrémiste, mais à mon sens, on doit pouvoir comprendre ce que fait le code en lisant le code seul(histoire de pouvoir le maintenir facilement), et on doit pouvoir comprendre ce que fait le code - et pourquoi - en ne lisant que les commentaires.

Encore une fois, si je dois "créer un processus de paiement par TIP si l'indicateur de type de paiement est à TIP et que le montant est inférieur à 1 million d'euros, parcequ'àprès, le montant, n'entre plus dans les cases préimprimées", alors un nom de variable/méthode/procédure qui me dira tout ça sera illisible tellement il sera long

Code:

---

1 2 3 4 5 6 7 8 9 10 11 12

'Émission de l'avis de paiement, en fonction du type de paiement : 'Un TIP ne peut pas dépasser 1M d'euros en raison de la taille du pré-imprimé Sub EmissionAvisPaiement(Client, Montant) Select Case True Case Client.PaiementPrefere = TypePaiement.Virement Call EmisionVirement(Client, Montant) Case (Client.PaiementPrefere = TypePaiement.TIP) and (Montant < 1000000) Call EmissionTIP(Client, Montant) Case Else Call EmissionCheque(Client, Montant) End Select End Sub

---

J'ose prétendre qu'on peux comprendre ce que fait mon code en le lisant. Pour autant, il faut quand même se farcir quelques lignes. Ma première ligne de commentaire résume tout ça. La deuxième, elle donne une précision sur le pourquoi. En effet, cette règle du million n'est pas évidente. Si quelqu'un arrive après, il saura ainsi pourquoi on fait ça(le reste est à peu près évident, j'espère).

Citation:

---

Envoyé par el_slapper

J'ose prétendre qu'on peux comprendre ce que fait mon code en le lisant. Pour autant, il faut quand même se farcir quelques lignes. Ma première ligne de commentaire résume tout ça. La deuxième, elle donne une précision sur le pourquoi. En effet, cette règle du million n'est pas évidente. Si quelqu'un arrive après, il saura ainsi pourquoi on fait ça(le reste est à peu près évident, j'espère).

---

Pour moi ton commentaire n'a pas sa place dans le code, sa place est dans des spécifications fonctionnelles... Le mettre dans le code signifie qu'uniquement le développeur aura connaissance de ca, pas le MOA. Pire que ca, ta règle a de grandes chances d'être en triplon (oui je viens de créer ca) (code + commentaire + specs) et ca augmente encore plus le potentiel de désynchronisation entre les trois.

Un code correctement construit et nommé accompagné d'une doc (mais pas dans le code) fonctionnelle, ca c'est utile, car même un non codeur peut reprendre la doc !

PS chipotage: en plus ton code il marche pas, car même avec un montant supérieur à 1M on tombe dans le else qui envoie un TIP :aie:

Citation:

---

Envoyé par Nathanael Marchand

Pour moi ton commentaire n'a pas sa place dans le code, sa place est dans des spécifications fonctionnelles... Le mettre dans le code signifie qu'uniquement le développeur aura connaissance de ca, pas le MOA. Pire que ca, ta règle a de grandes chances d'être en triplon (oui je viens de créer ca) (code + commentaire + specs) et ca augmente encore plus le potentiel de désynchronisation entre les trois.

---

Ben, la première année, tu as raison. Quand j'ai récupéré ce code - non commenté - il avait 36 ans d'âge. Les gens qui avaient écrit la spec étaient morts, ceux qui avaient écrit le code était à la retraite depuis deux décennies, et la doc, eh bien personne ne savait à quoi elle avait bien pu ressembler à l'époque. Il a fallu plusieurs semaines(pas à plein temps) aux MOA pour remonter jusqu'à l'origine de cette verrue.

Avec les années, les rachats, les réorganisations, les déménagements, le source, c'est tout ce qui reste. Donc il est essentiel de mettre le pourquoi dans le code.

Évidemment, quand on créée le code, au départ, lors du projet initial, ça parait con. Mais pour celui qui passe après, non pas celui-là, l'autre, bien longtemps après, c'est vraiment utile.

Citation:

---

Envoyé par Nathanael Marchand

Un code correctement construit et nommé accompagné d'une doc (mais pas dans le code) fonctionnelle, ca c'est utile, car même un non codeur peut reprendre la doc !

---

Et il en fait quoi? Soit c'est une spec fonctionelle, et c'est aux gens des métiers de le faire vivre, soit c'est un code, et c'est à nous développeurs.

Citation:

---

Envoyé par Nathanael Marchand

PS chipotage: en plus ton code il marche pas, car même avec un montant supérieur à 1M on tombe dans le else qui envoie un TIP :aie:

---

Corrigé. :aie:

Bonjour,

Personnellement, pour moi un code est bien écrit s'il a des commentaires mais je ne met pas des commentaires à chaque lignes non plus.

J'essaye surtout de commenter tout ce qui se trouve dans les header (méthodes, fonctions, attributs, enum, ...) ce qui me permet d'expliquer les tenants et les aboutissants des méthodes, de rajouter des notes et des warnings afin qu'on puisse tout réutiliser sans nécessairement se replonger dans le code.

De plus, cela me permet de générer une documentation doxygen qui est aussi très pratique pour réutiliser le code sans le relire.

Ensuite, se fier uniquement à des noms explicite est ridicule.
Il y a toujours des personnes qui penseront autrement que nous et qui utiliseront mal notre méthode s'ils ne lisent pas la documentation, donner des noms de fonctions à rallonge ne corrigera pas totalement ce problème.

Les noms explicites doivent aider à la compréhension du code mais seuls, ils ne peuvent pas nous dire exactement comment utiliser le code.
Un bon code est un code dans lequel on a plus à se replonger dedans et à comprendre exactement comment il fait pour pouvoir l'utiliser.

Ensuite dans les fichiers sources je ne met que très rarement des commentaires, le code étant assez souvent assez explicite pour qui veut le relire ( et la documentation aidant aussi à la compréhension ) mais lorsque je le juge nécessaire, je peux rajouter des commentaires, après tout cela ne coûte rien (à part le temps pour l'écrire) et c'est tout bénéfice ;)

Dans l'absolu (vers lequel on doit se diriger), je suis super d'accord avec ce mec, il ne devrai jamais y avoir de commentaire. Si l'espace de nom, la classe, la signature de la méthode et l'organisation du code sont corrects, nul besoin de commentaire, le code parle de lui-même y compris à un débutant.
Dans la vraie vie, il en va différemment, car il arrive toujours un moment où le choix d'un nom n'est pas évident (et on a pas le temps de trouver un truc nickel), où pour aller plus vite on écrit un algo difficile à déchiffrer, des lignes trop longues, et des paramètres équivoques ou polyvalents. Dans ces cas là, les commentaires sont nécessaires. A fortiori si il s'agit d'interfaces, ou de méthodes publiques.
Notez que le "pourquoi" d'un code peu également être explicité par son fichier de test unitaire (encore un argument qui confirme que le TDD est une bonne pratique).

Parfois, lorsqu'on met au point un algo compliqué, et qu'on utilise des moyens contre-nature pour l'optimiser, il faut le commenter et si possible dans les moindres détails. L'inverse s'est se tirer une balle dans le pied.
Personnellement, j'abonde mon code de commentaires. C'est tellement rapide de taper une ligne pour expliquer ce qu'on fait... et tellement de temps gagné quand il faudra venir le modifier. Je bosse en R&D, alors le code jetable je connais !

En fait les commentaires, c'est un peu ce qui permet de bosser de manière inconsciente, sans devoir réfléchir à décortiquer le code. C'est l'étiquette sur le pot de confiture qui permet de pas se tromper entre groseille et framboise, sans avoir besoin de l'ouvrir et de le goûter (le drame!).

Et puis le petit plus, c'est de pouvoir générer la doc avec doxygen ou autre. Bref, je ne comprend surtout pas pourquoi on doit s'en priver. Après c'est peut-être moins valable quand on développe des applis type gestion ou le nom des variables & méthodes sont assez évocateurs. Enfin je suppose...

Citation:

---

Envoyé par Nathanael Marchand

Pour moi ton commentaire n'a pas sa place dans le code, sa place est dans des spécifications fonctionnelles... Le mettre dans le code signifie qu'uniquement le développeur aura connaissance de ca, pas le MOA. Pire que ca, ta règle a de grandes chances d'être en triplon (oui je viens de créer ca) (code + commentaire + specs) et ca augmente encore plus le potentiel de désynchronisation entre les trois.

Un code correctement construit et nommé accompagné d'une doc (mais pas dans le code) fonctionnelle, ca c'est utile, car même un non codeur peut reprendre la doc !

PS chipotage: en plus ton code il marche pas, car même avec un montant supérieur à 1M on tombe dans le else qui envoie un TIP :aie:

---

puisque le sujet déchaîne toujours les passions, je ne résiste pas à y mettre mon grain de sel.

dernier exemple en date :

- spécification :
* un fichier de données est créé avec les commande du jour, le fichier sera nommé "data-yyyy-mm-dd.dat" où yyyy-mm-dd représente la date du jour.
* les données du jour ne sont pas reprise le lendemain

- réalisation :
* $filename = 'data-'.date('Y-m-d').'.dat';
* if (date('Ymd') != $curdate) { $data = array(); $curdate = date('Ymd'); }

- réalité : la procédure s'exécute à 00:00 crée un fichier pour J+1 avec les données du jour J

- modification : $filename = 'data-'.date('Y-m-d', time() - 1 * 60 * 60).'.dat';

ça c'est un exemple réel (pas en PHP mais peu importe), la création du fichier J+1 perturbe de plus le fonctionne de l'appli, donc pour éviter le bug, sachant qu'il n'y a pas de commande entre 23h et 11h le lendemain, en retirant 1h à la date courante pour calculer le nom du fichier on tombe toujours sur le "bon" jour. Ce n'est pas un problème de spécification mais d'implémentation. Je place très souvent des commentaires sur le code beau et propre initiale qui a été modifié pour corriger un bug car ce bug n'étant pas évident à la lecture du code il est nécessaire d'attirer l'attention du lecteur sur l'importance de la modification.

allez aussi savoir sans commentaire pourquoi le code est en réalité : $filename = 'data-'.gmdate('Y-m-d', time() + 3 * 60 * 60).'.dat'; !

Un bon code doit, selon moi, avoir des commentaires fonctionnels ayant un apport supplémentaire.

Il est évident que du commentaire basique décrivant le code n'est pas intéressant.

Les commentaires sont importants. Dire que si un code a besoin de commentaire, c’est qu’il faut changer le code lui-même, c’est très con. Certaines lignes de hack ou hardware peuvent nécessiter des explications, exemple très simple l’isqrt de Carmack.

Bonjour.

Je suis très controversé sur les commentaires. Je trouve cela très utile et très chiant.

Quand je découvre un code écrit par une autre personne, c'est sympa d'avoir des commentaires de partout. Ca évite parfois de lire 15 pages de specification :mouarf:

Par contre quand je code, les commentaires c'est gonflant. Il y a du vert de partout, une fonction de 20 lignes en fait 50, le cadre de travail est exécrable. Il faut scroller sur deux/trois pages, on ne peut pas avoir une vision d'ensemble correcte sur la fonction. Bref c'est comme le code trop aéré, selon moi, tout cela nuit à une bonne maintenance du code. Si on débuge une fonction qui tiens sur l'écran, ce sera plus facile de trouver l'erreur que dans le cas ou il faut scroller et re-scroller et re... A moins d'avoir une mémoire d'einstein.

Je ne vous parle même pas des projets qui contiennent des fonctions de 100 lignes de code avec 10/15 accolades ouvrantes. Rajouter des commentaires là-dessus, et c'est du grand n'importe quoi. Vous passez plus votre vie à scroller qu'à programmer.

Donc je suis mitigé.

Pour la lecture d'un code inconnu, les commentaires, c'est bien.

Quand on code, on sait ce que l'on fait. Donc commenter ce que l'on fait, ça fait doublon sur le coup. Personnellement, lorsque je code, j'ai aussi hâte de voir le résultat. Parce que commenter un code que je vais modifier 50 fois, donc recommenter 50 fois... J'exagère, mais quand vous codez tous les jours, ça prends des proportions énormes.

Bref, comment conjurer ces deux aspects.

Pour ma part :

un code le plus simple possible. Des nommages explicites et peu de commentaires.
A côté de cela, je fournis un schéma architectural du projet lorsqu'il est stable (cela permet d'avoir une vision d'ensemble du projet. Je pense que c'est mieux qu'un roman de spécification, qui sera plutôt dédié au concepteur de bibliothèque).
Lorsque j'ai le temps, je fournis un schéma fonctionnel, histoire d'entrer un peu plus dans les détails du projet.

Tout cela pour dire que les schémas/diagramme me sont beaucoup plus utiles que du roman/commentaire, lorsque je dois reprendre du code.

Mais chacun sa méthode. S'il y avait une méthode universelle, on ne sera pas là à épiloguer sur les commentaires.

L'idéal serait d'avoir un code commenté entièrement, et un code sans commentaire. L'un pour la lecture et la découverte, l'autre pour la maintenance et le débugage. Un IDE du futur quoi.

À lire toutes ces réponses j'en conclus, que quelque soit la durée de vie du code, quelque soit le développeur :
- Il existe toujours un document de spécification, accessible, qui correspond exactement à ce que fais le programme, et dont la spécification pour le code examiné est identifiable aisément.
- Toutes les subtilités du langage de programmation utilisé sont parfaitement connues.
- Tous les algorithmes, pourvus qu'ils soient identifiés, son parfaitement connus.
- Toutes les API utilisées sont parfaitement connues, dans toutes les versions.

Donc de toute manière, le commentaire ne sert à pas grand chose, tout développeur code de manière suffisamment claire. En fait si quelqu'un fait remarquer qu'un commentaire aurait été utile pour telle ligne de code, RTFM, ou va te former ?

Or un code est fait pour rester en vie quelques années, alors même que :
- telle API n'est plus à la mode
- tel algorithme était super connu par le développeur, mais en fait très spécifique et trouvable que dans un ouvrage inconnu du développeur lambda
- un bug a entrainé la correction du code pour que cela fonctionne dans tous les cas, sans que la spécification en soit changée.
- le développeur n'est pas un spécialiste du langage utilisé, et il existe une meilleure solution que le code existant (et inversement)

En plus, dire que le bon code n'a pas besoin de commentaire, c'est être présomptueux et déclarer que c'est forcément le bon choix de programmation qui a été fait. Or nous ne sommes jamais à l'abri d'une erreur, ou d'une ignorance.

Un bon code doit être compris avec un minimum de commentaires. Des noms suffisamment explicites pour les variables, classes, méthodes, fonctions, etc. peuvent déjà en éviter pas mal. Et puis tant pis si des fois ces noms sont un peu longs. Au pire un bon IDE/éditeur a toujours une fonction d'autocomplétion type "CTRL + Espace" pour compléter rapidement le nom à rallonge en question.

Me concernant, j'utilise les commentaires pour décrire les grandes étapes de mon code avec un résumé au début de chaque grosse partie pour expliquer ladite partie. Je suis d'accord que certaines grosses parties de codes peuvent être remplacées par des fonctions ou méthodes mais à beaucoup trop morceler le code, on perd en compréhension.

J'en mets également à certains endroits pour expliquer par exemple que tel ou tel choix peut-être dû à un bug qu'il a fallu fixer avec cette solution particulière : "J'ai fait comme ci plutôt que comme ça sinon il y a tel bug qui se produit". Un genre de "Faut pas toucher à cette partie sinon ça marche plus", mais avec la raison pour laquelle ça ne marcherait pas. Comme par exemple un workaround autour d'un bug (non résolu) d'une librairie (ça m'est déjà arrivé).

Je pense aussi que maintenir les commentaires à jour au fur et à mesure des modifications du code est une bonne pratique qui se doit d'être respectée. Les commentaires indiquent les choses qui se passent, pas celles qui se sont passées par le passé et qui ne se passent plus dans le présent. C'est bête à dire mais encore faut-il le rappeler.