Discussion :

[martopioche]

Oui martopioche, nous avons tous bien compris que c'est toi le meilleur... et que ceux qui écrivent du code procédural sont des porcs.


Anecdote personnelle au sujet des commentaires :

Merci pour le sophisme, mais en ce qui me concerne, je ne parle pas de moi et ne généralise pas mes anecdotes, pratiques courantes sur les forums. Je cite des pratiques qui font consensus et ont fait leurs preuves. Ça ira mieux si je te dirige vers des ouvrages comme Clean Code de Robert Martin ?

[Pyramidev]

- vous ne connaissez pas les IDEs ? Outils super pratiques qui permettent en général de naviguer dans le code

D'une part, quand je fais une comparaison de code entre deux révisions SVN, le code n'est pas ouvert dans un IDE.
D'autre part, même avec un vrai IDE, rien n'est plus rapide qu'avoir directement le code sur place, sous les yeux.

- pourquoi voir l'implémentation ? Si vous trouvez en Python print() ou en Java System.out.println() (ou l'équivalent dans d'autres langages), avez vous l'envie de voir l'implémentation ? Donc pourquoi y aller pour filterOffensiveWords() ?

Par exemple, cela peut arriver si la documentation technique ne précise pas sur quel critère le programme se base pour déterminer si un mot est injurieux voire ne précise pas que le programme filtre les mots injurieux.
Scénario possible : Un client se plaint qu'un certain mot ne soit pas pris en compte. Le help desk ne reproduit pas le problème en local et me le retransmet. Je découvre que le code appelle filterOffensiveWords() et je soupçonne cette fonction d'avoir filtré le mot chez le client mais pas chez moi. J'ai besoin de savoir comment elle marche. Je lis son code et je découvre que la liste des mots injurieux se base, entre autres, sur un fichier de préférences du client. Je complète alors des documentations dont celle destinée au help desk pour que, la prochaine fois, le personnel du help desk regarde dans le fichier de préférence du client avant de me retransmettre le problème.

Quand le ticket sera corrigé, qui ira mettre à jour les commentaires ? Quand quelqu'un relira cette partie, qui ira vérifier si le ticket a été fermé ?

Personnellement, quand j'écris un commentaire relatif à un ticket, je complète le ticket et j'y écrit "Voir les occurrences de XXXX (le numéro du ticket) dans le code". Du coup, il y a un léger espoir que celui qui aura corrigé le ticket mettra à jour le commentaire.
Sinon, si le commentaire n'a pas été mis à jour et que quelqu'un le lit, il se peut qu'il cherche à avoir plus d'informations en consultant le ticket puis découvre que le ticket est fermé. Alors, il devrait supprimer le commentaire.

• Pour laisser du code mort. Par exemple un test qu'on a retiré parce qu'il [est/ semble] inutile, mais on le laisse en commentaire au cas où, ou alors un bout de code qu'on a réimplémenté.
• Bonus un petit "// <- XXX" pour préciser tout le code qui doit être supprimé dans le code final. Ce commentaire n'est pas nécessaire ni suffisant, mais au moins ce code peut-être est supprimé sans trop de réflexion lors de la relecture finale/ tests finaux

Au cas où quoi ? Qui va décommenter du "code mort" ???

Gné ??? C'est quoi le "code final" ?

On dirait que je fais pareil que foetus.
Parfois, lors d'un développement, j'ai besoin d'avoir sous les yeux comment étaient certaines portions de code juste avant que je ne les modifie, sans perdre du temps à chercher la précédente version dans la dernière révision SVN. Alors, au lieu de supprimer tout de suite l'ancienne portion de code, je la mets en commentaires. Quand le développement est fini et qu'il semble bien marcher, je supprime le code mort avant le commit.

[martopioche]

D'une part, quand je fais une comparaison de code entre deux révisions SVN, le code n'est pas ouvert dans un IDE.
D'autre part, même avec un vrai IDE, rien n'est plus rapide qu'avoir directement le code sur place, sous les yeux.

Si sur le principe c'est vrai, dans le premier cas, tu organise ton code pour un cas particulier (comparaison d'historique) plutôt que pour un usage plus général (lecture du code). Simple stat : combien de fois un lecteur parcours un code vs compare des historiques ?

Pour le second, je ne suis pas convaincu : qu'apporte le code du filtre de mots sur le reste ?

Par exemple, cela peut arriver si la documentation technique ne précise pas sur quel critère le programme se base pour déterminer si un mot est injurieux voire ne précise pas que le programme filtre les mots injurieux.
Scénario possible : Un client se plaint qu'un certain mot ne soit pas pris en compte. Le help desk ne reproduit pas le problème en local et me le retransmet. Je découvre que le code appelle filterOffensiveWords() et je soupçonne cette fonction d'avoir filtré le mot chez le client mais pas chez moi. J'ai besoin de savoir comment elle marche. Je lis son code et je découvre que la liste des mots injurieux se base, entre autres, sur un fichier de préférences du client. Je complète alors des documentations dont celle destinée au help desk pour que, la prochaine fois, le personnel du help desk regarde dans le fichier de préférence du client avant de me retransmettre le problème.

Ce cas est plutôt un contre exemple… :p
Sur cette anecdote, tu est bien d'accord que ton process est d'écrire un test d'appel à filterOffensiveWords() avec le mot particulier et voir voir que ça marche chez toi, puis vérifier ce code et je ne vais pas paraphraser ce que tu a écris. Oui tu complète la documentation (pour moi ça commence par la fonction filterOffensiveWords() en ajoutant "filtre basé sur le fichier de préférences"), mais le découpage en fonction t'a permis de cibler plus rapidement le problème. D'ailleurs, si la doc de la fonction est déjà à jour, tu a demandé au helpdesk si ils ont vérifié ça avant même de tester…

Personnellement, quand j'écris un commentaire relatif à un ticket, je complète le ticket et j'y écrit "Voir les occurrences de XXXX (le numéro du ticket) dans le code". Du coup, il y a un léger espoir que celui qui aura corrigé le ticket mettra à jour le commentaire.
Sinon, si le commentaire n'a pas été mis à jour et que quelqu'un le lit, il se peut qu'il cherche à avoir plus d'informations en consultant le ticket puis découvre que le ticket est fermé. Alors, il devrait supprimer le commentaire.

"Personnellement", "espoir", "si", "il se peut", "il devra"…*Tu ne trouve pas que ça fait un peu trop pour espérer que ce soit fait ? De plus, c'est en contradiction avec ce que tu dis avant à propose de la rapidité d'avoir l'information. Car à nouveau :
- Si le ticket n'a aucun rapport avec ce bout de code (le ticket a une influence sur ce comportement mais ne le concerne pas directement), celui qui traite le ticket ne verra jamais ce commentaire
- Si le lecteur de ce code n'est pas concerné par un problème lié à la description du commentaire, il n'ira jamais voir le ticket…

Admet que ces deux cas sont des certitudes…

On dirait que je fais pareil que foetus.
Parfois, lors d'un développement, j'ai besoin d'avoir sous les yeux comment étaient certaines portions de code juste avant que je ne les modifie, sans perdre du temps à chercher la précédente version dans la dernière révision SVN. Alors, au lieu de supprimer tout de suite l'ancienne portion de code, je la mets en commentaires. Quand le développement est fini et qu'il semble bien marcher, je supprime le code mort avant le commit.

Ce que tu décris est différent de ce que j'ai compris de foetus. Faire évoluer du code en le réécrivant et pour ça commenter l'ancien le temps de la réécriture, je ne vois pas le problème, ça reste une action personnelle qui ne quitte pas la version locale et la publication est propre. Dans le cas de foetus, j'ai cru comprendre que ce code mort reste ad-vitam aeternam "au cas où"…

[Bryce de Mouriès]

Faisons rapide et simple :

1. Introduire une variable explicative
Non, je vais pas rajouter une variable inutile.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.

2. Extraire une méthode
Toujours non, je vais pas empiler des appels inutiles.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.

3. Utiliser un nom d'identificateur plus descriptif
Là c'est assez évident. Maintenant il peut arriver qu'on se retrouve avec des noms sans fin, on peut alors contextualiser les variables avec un petit commentaire (dans l'exemple, en tête d'algo, indiquer "all sizes in pixels" ).

4. Ajouter un contrôle dans le cas où votre code a des hypothèses
Gné ? Faire du défensif pour économiser un commentaire ? Là je sais même pas quoi dire ...

Complètement d'accord avec toi jopopmk, je me faisais la même réflexion. Ecrire plus de code pour éviter de taper un commentaire ?!? Cela sera forcément moins clair car moins détaillé, et cela demande plus de travail. En plus si on est puriste ça dégrade infimement les perfs.

Je trouve que ça a très vite ses limites le beau code que l'on est sensé comprendre sans aucun commentaire, c'est assez subjectif, je préfère largement lire les commentaires jusqu'à trouver l'endroit qui m'intéresse plutôt que lire le code, lire le code c'est comme lire une langue étrangère, on aura beau la connaître il y a toujours un travail de traduction dans la tête. Alors que lire un texte se fait naturellement. Le premier exemple le montre très bien, avec commentaire on sait immédiatement que c'est l'application d'une réduction, il n'est même pas utile de lire le code.

Après on est jamais seul sur un projet (je considère que le moi du futur est une autre personne qui ne comprendra peut être pas ce que le moi du présent a bien pu avoir en tête quand il a écrit son code...).

[Sodium]

Complètement d'accord avec toi jopopmk, je me faisais la même réflexion. Ecrire plus de code pour éviter de taper un commentaire ?!? Cela sera forcément moins clair car moins détaillé, et cela demande plus de travail. En plus si on est puriste ça dégrade infimement les perfs.

Plus de code ? Non, car factoriser son code oblige à réfléchir à ce que l'on fait et généralement à le simplifier.
Moins clair car moins détaillé ? Absolument pas.
Plus de travail ? Encore une fois non, car un code moins complexes est plus facile à maintenir.
Dégrader les perfs ? Pratiquement tous les compileurs ou interpréteurs se foutent complètement de la façon dont est écrit le code et l'optimisent très bien, à moins bien sûr d'avoir fait n'importe quoi.

[Bryce de Mouriès]

Plus de code ? Non, car factoriser son code oblige à réfléchir à ce que l'on fait et généralement à le simplifier.
Moins clair car moins détaillé ? Absolument pas.
Plus de travail ? Encore une fois non, car un code moins complexes est plus facile à maintenir.
Dégrader les perfs ? Pratiquement tous les compileurs ou interpréteurs se foutent complètement de la façon dont est écrit le code et l'optimisent très bien, à moins bien sûr d'avoir fait n'importe quoi.

On le voit bien dans les 4 exemples, il y a plus de codes. Les IDE nous aide pas mal aujourd'hui, ça reste toujours plus long que d'écrire une phrase, la finesse du langage permet toujours d'être plus précis

Honnêtement tu trouves ça

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
price = numItems * itemPrice;
discount =
    min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;

plus clair que ça ?

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

// Subtract discount from price.

Après je suis d'accord, ça n'est pas une raison pour écrire tout son code sur une ligne parce qu'on a mis un commentaire juste au dessus.
Ne tient pas compte de moins commentaire sur les perfs, c'était pour troller

[martopioche]

Ecrire plus de code pour éviter de taper un commentaire ?!? Cela sera forcément moins clair car moins détaillé, et cela demande plus de travail.

Moins clair car moins détaillé ? Qu'est ce qui est un "détail" acceptable ? Et plus le commentaire est long, qui prend le temps de le lire ? Quand à plus de travail…*Quel est la quantité de travail nécessaire pour déterminer un nom de variable "parlant" vs formuler une explication compréhensible ?

Je trouve que ça a très vite ses limites le beau code que l'on est sensé comprendre sans aucun commentaire

On ne parle pas de "beau code" ni de code sans aucun commentaire.

je préfère largement lire les commentaires jusqu'à trouver l'endroit qui m'intéresse plutôt que lire le code, lire le code c'est comme lire une langue étrangère, on aura beau la connaître il y a toujours un travail de traduction dans la tête. Alors que lire un texte se fait naturellement. Le premier exemple le montre très bien, avec commentaire on sait immédiatement que c'est l'application d'une réduction, il n'est même pas utile de lire le code.

Sauf que cet exemple est un… exemple. Qui illustre un usage et qu'il n'est pas représentatif de la vie du code. Plus le commentaire (et plus généralement la documentation) est "grosse", mois elle est maintenue. Et personne ne peut "garantir" que le commentaire dans 10 modification décrira ce qui se passe en dessous. Alors, en plus de ton "travail de traduction", tu va le compléter avec un travail de compréhension de "mais quel rapport" ???

Edit (pour ne pas multiplier les interventions) : pour ton exemple de quel cas est le plus "clair", évidemment que pour un humain pour la simple lecture le commentaire est plus évidente, mais dans quel contexte parcours-tu le code ? Le commentaire décrira l'intention, la lecture du code montrera l'action. On n'écrit pas du code à but pédagogique (la plupart du temps) mais pour qu'il soit exécuté et maintenu, et pour la maintenance, va-tu te reposer sur l'intention ou sur l'implantation sachant à quel point tout ce qui relève de la documentation est maintenu ?

Après on est jamais seul sur un projet (je considère que le moi du futur est une autre personne qui ne comprendra peut être pas ce que le moi du présent a bien pu avoir en tête quand il a écrit son code...).

Exactement, et c'est avant tout pour ces cas là que ces principes de bonnes pratique ont émergés.

[Invité]

J'aime bien lire ce genre d'article. Ça me rappelle à qu'elle point une architecture propre et logique facilite la maintenance (parce que le mec connait le système pour lequel il code) autant que les commentaires. Dans ce cas, ce genre d'article est tout à fait pertinent.

Sinon le challenge c'est de comprendre l’esprit tordu qui à écrit le code, et les commentaires que vous trouverez dedans seront tout aussi tordu et dénué de sens et ne vous aiderons pas beaucoup plus.

[MikeRowSoft]

Et vous ?

À quelle fréquence pensez-vous utiliser des commentaires ? Rarement, souvent, très souvent ?
Quelles règles observez-vous pour insérer des commentaires dans votre code ?

Les enseignants en pensent quoi ?

J'ai plus eu des conseils, sachant que très souvent la modélisation comportait déjà les commentaires.

Quelques rares fois, il était obligatoire de mettre quelques "repères" supplémentaires lors de l'implémentation. Surtout lors de la découverte par la pratique de framework ou librairies. Mais en aucun cas ces commentaires seraient utiles hors de la phase d'apprentissage.

Quelles règles observez-vous pour insérer des commentaires dans votre code ?

Surement pour un algorithme très tordu... Comme afficher une formule mathématique en HTML avec un clavier qui ne connait pas i de C...

[Pierre Fauconnier]

Quid du commentaire "inutile" qui permet d'autogénérer la doc?

[martopioche]

Et ? T'as jamais vu du code vieux de plusieurs dizaines d'années ? Tu peux aller voir ton patron et dire "bon mec, notre code il marche mais il a 30 ans, faut le changer, on est en 2017 !" ? Et il accepte et est prêt à changer un truc qui marche sans broncher parce que tu lui montres un livre ?
Bienvenue dans le monde réel.

Mais quel est le rapport avec l'âge du code ? La question est une question sur la pratique actuelle. Foetus, qui est celui que je citais, rebondissait sur "j'écris…", pas "j'écrivais il y a 30 ans…". Parce que le code a 30 ans, les pratiques restent figées à il y a 30 ans ?

Et truc qui marche sans broncher…*Si par ce process, il livre avec du code de dev ou qu'après la livraison les devs ont du code de prod, on est bien d'accord que ce truc "ne marche pas", non ?

Tout refaire cela chiffre en milliards d'euros.
Je suis assez de l'avis des autres intervenants martopioche, soit tu troll soit tu ne sais absolument pas de quoi tu parles...

Sauf que ce n'est pas moi qui parle de tour refaire…

Tu cites un livre pour dire que tes propos ne viennent pas de ton expérience généralisée mais j'ai plutôt l'impression que tu n'as pas lu correctement ce dit livre et que tu généralises à tout va ce que tu en as compris...

Ok, tu en a l'impression, tu en a compris quoi toi ?

[Programming-Z]

En générale, les commentaires ne sont pas nécessaires si on défini correctement les noms des variables et fonctions.

Quand on insère plus de ligne de commentaire que de code, c'est qu'il y a un problème quelque part (mentalement surement )

[Sodium]

J'essaye de passer le plus possible par des fonctions ou des variables temporaires au nom évocateur.
J'en utilise généralement quand l'utilité d'un bout de code n'est pas évidente, que ça soit pour moi-même ou pour d'autres personnes ayant éventuellement à le relire.
C'est là que l'on trouve les limites des outils tels que PHPMetrics qui donnent beaucoup d'information utiles mais ont la mauvaise idée d'évaluer l'accessibilité d'un code par le ratio commentaires / opérations.

À l'inverse, la personne avec qui je travaille ne juge utile ni de factoriser, ni de commenter son code, peu importe le nombre de milliers de lignes et le côté cryptique de celles-ci, ce qui devient rapidement ingérable.

[Cincinnatus]

..., la personne avec qui je travaille ne juge utile ni de factoriser, ni de commenter son code, peu importe le nombre de milliers de lignes et le côté cryptique de celles-ci, ce qui devient rapidement ingérable.

Bon courage... J'ai déjà eu à reprendre du code (PHP ) qui était de ce style. Fonctions dupliquées mais écrites différemment, conditions à rallonge simplifiées avec un peu de logique, ...

[Aizen64]

Pour ma part, hormis le fait d'être assez verbeux sur le nom des variables, j'ai tendance à faire 2 choses :
- documenter quand je l'estime nécéssaire, assez souvent en fait, d'autant plus quand je dois coder en dur certains id qui correspondent à des données en base,
- tout fichier/classe possède des docBloc, toutes les méthodes sans exception fournissent dans le docBlock le type, le nom de la variable et une description précise et ce même si nom de variable est assez explicite,
- tout paramètre de configuration est aussi documenté avec son type et une description, l'idée m'est venue en modifiant des fichiers de conf de SGBD,
- quand l'ordre de chargement de fichier n'est pas forcément évident, pour un framework et ces différents fichiers de config, l'ordre est fourni dans un commentaire en début de fichier

Oui c'est verbeux, et ça prend du temps à faire si on ne le fait pas dès le début mais par la suite, ça peut aider de nouveaux venus et les IDE aident pas mal pour récupérer ces docs automatiquement.

[clementmarcotte]

Faisons rapide et simple :

1. Introduire une variable explicative
Non, je vais pas rajouter une variable inutile.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.

Là j'avoue que cela sort un peu du sujet, mais à la limite, cela peut faire penser à un effet collatéral. Ajouter une (des) variable(s) inutile(s) et faire un traitement sur 2 ou 3 lignes peut faciliter le débogage.

Ceci dit, je dirais qu'il y a au moins trois occasions où des commentaires sont pratiquement obligatoires, ne serait-ce que par respect pour lecteurs.

1) Quand on veut déposer le programme-source sur un site où de parfaits débutants pourraient l'utiliser

2) Quand on est obligé, pour des raisons d'optimisation, ou d'autres raisons techniques, d'utiliser une sorte de "passe croche" inédite ou inconnue. (Ne serait-ce que parce que la mémoire est une faculté qui oublie)

3) Quand on sait que le programme peut être utilisé très longtemps. (Comme les antiques programmes en COBOL avec des années à juste deux chiffres qui étaient encore là en 1999.)

[Invité]

Quels beaux exemples, prenons le premier avec la variable explicative :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
price = numItems * itemPrice;
discount =
    min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;

Pourquoi est-ce le minimum entre 5 et le nombre d'items ?
Un petit commentaire explicatif ?

genre
//réduction totale = -10% prix unitaire, sur 5 articles au maximum

Et la valeur de discount unitaire en dur, très propre

[martopioche]

Mais, précisément, comment savoir qui va reprendre le code dans l'avenir ? Donc, ne faut-il pas toujours commenter ?

Si la question est par rapport à ta citation, la question est simple : c'est quoi le but de ton job ? Si c'est faire de l'enseignement, oui. Si c'est produire du code et le maintenir, on va supposer qu'il sera repris par un développeur. Si celui qui reprends ce code n'a pas "la compétence", ce n'est pas à toi de compenser l'incompétence du management qui ne sait pas staffer ses équipes.

C'est sûr si tu pars du postulat "un commentaire ne sera mis à jour", autant rien commenter

Allez, on va être pragmatiques : peux-tu citer où j'ai fait ce postulat ?

Après si tu pars du postulat "Le code n'aura qu'une durée de vie de 2 ans", autant rien commenter

Là aussi : peut-tu citer où j'ai fait ce postulat ?

Mais dans la vraie vie, des fois, on n'a pas les outils pour

La vrai vie ? Ah, un commentaire qui indique que la suite de l'intervention sera su sophisme

Quels beaux exemples, prenons le premier avec la variable explicative :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
price = numItems * itemPrice;
discount =
    min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;

Pourquoi est-ce le minimum entre 5 et le nombre d'items ?
Un petit commentaire explicatif ?

Les commentaires n'ont pas pour but de recopier le cahier des charges ou la documentation fonctionnelle.

[Invité]

Si la question est par rapport à ta citation, la question est simple : c'est quoi le but de ton job ? Si c'est faire de l'enseignement, oui. Si c'est produire du code et le maintenir, on va supposer qu'il sera repris par un développeur. Si celui qui reprends ce code n'a pas "la compétence", ce n'est pas à toi de compenser l'incompétence du management qui ne sait pas staffer ses équipes.
[...]
Les commentaires n'ont pas pour but de recopier le cahier des charges ou la documentation fonctionnelle.

Les commentaires ont pour but de rendre le code compréhensible.

Tu préfères quoi ?
un code comme le premier exemple et "charge à toi" d'aller trouver dans la documentation le pourquoi du code ?
ou un code explicité avec un commentaire qui indique l'élément de difficulté, comme ici le "min(5,numitem)" pour la réduction ?

Ne crois-tu pas que ça permet de gagner BEAUCOUP de temps dans la lecture et sa compréhension ?

J'ai fais du dev avec gestion des requirements & TMA associée.

Donc chaque requirement était tracé dans les commentaires du code pour prouver que le requirement avait été réalisé par le bout de code identifié.
Et cela pour gérer le suivi des fonctionnalités et gérer la configuration logicielle
Par exemple, chaque anomalie/évolution était bornée de commentaires du genre :
/** début ano00001 **/
....
/** fin ano00001 **/

Maintenant, et c'est un avis personnel, je préfère plus de commentaire que moins de commentaires.
Je préfère une personne qui aura écrit tout son code en algorithme dans les commentaires avec le code associé en dessous,
qu'une personne qui fera tout sans AUCUNE ligne de code.

Bref, mieux vaut trop d'information que pas assez.
Parce que typiquement, oser croire que la documentation est toujours retrouvable et bien à jour, c'est naif

[Pyramidev]

Par exemple, chaque anomalie/évolution était bornée de commentaires du genre :
/** début ano00001 **/
....
/** fin ano00001 **/

C'est une convention qui date d'une ancienne époque. Maintenant, pour ce genre de chose, on utilise un logiciel de gestion de versions (en anglais, Version Control System ou VCS), comme SVN, Git et Mercurial.

Concrètement, quand tu as fini d'implémenter un ticket (évolution ou anomalie), tu fais un commit avec un petit commentaire, par exemple "ano00001" suivi d'une description brève.
Ensuite, quand tu as besoin de voir l'évolution d'un fichier, via le logiciel de gestion de versions, tu peux voir la liste des commits rangés par ordre chronologique qui concernent ce fichier.
Pour chaque commit, tu peux voir la date, le petit commentaire et la liste des fichiers que ce commit a modifiés.
Pour chacun de ces fichiers, tu peux aussi voir la liste des différences avant et après le commit.

Rq : martopioche parle de SCM (Source Code Manager). Je crois que le sens est similaire à celui de VCS.