Discussion :

[Michael Guilloux]

Programmation : quand faut-il commenter son code ? Google s’invite dans le débat
et montre que les commentaires peuvent très souvent être évités

En apprenant la programmation, votre professeur vous a certainement dit de toujours et bien commenter votre code. Rappelons que les commentaires sont des portions du code source ignorées par le compilateur ou l’interpréteur, car ils ne sont pas nécessaires à l’exécution du programme. Ils sont généralement insérés dans le code afin qu’il soit facile à comprendre et de sorte qu’on puisse le modifier facilement à l’avenir. Mais certains en font peut-être un peu trop avec les commentaires, en essayant de les placer à chaque petit coin du code ; une pratique qui est désapprouvée par beaucoup de développeurs expérimentés.

Pour ces derniers, si le code est tellement compliqué que cela doit être expliqué, il est presque toujours préférable d’améliorer le code que d’ajouter des commentaires. Dans un billet de blog datant de 2013, un développeur .NET du nom de Steve Smith a donc voulu trancher le débat en expliquant que « les commentaires doivent être généralement évités si le code peut dire ce qu’il fait. » Steve Smith pense en effet que « les bons commentaires disent ce que le code ne peut pas exprimer, comme pourquoi une technique particulière a été favorisée ou les dangers de l’optimisation d’un bloc de code. La plupart des autres types de commentaires sont simplement du bruit et leur présence encombre le code. »

Malgré tous les avis sur la question, la manière d’utiliser les commentaires reste une vieille question dans les habitudes de programmation. Google s’invite aujourd’hui dans le débat et montre qu’en réalité les commentaires peuvent très souvent être évités. « En lisant un code, souvent, il n'y a rien de plus utile qu'un commentaire bien placé. Cependant, les commentaires ne sont pas toujours bons. Parfois, le besoin d'un commentaire peut être un signe que le code devrait être refactorisé. Utilisez un commentaire lorsqu'il est impossible de faire en sorte que votre code s'explique par lui-même », expliquent Dori Reuveni et Kevin Bourrillion sur Google Testing Blog.

Si vous pensez avoir besoin d'un commentaire pour expliquer ce qu'est un code, ils proposent alors de procéder d'abord à l'une des opérations suivantes :

1. Introduire une variable explicative
Avec commentaire :

Code :

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

1
2
3
// Subtract discount from price.
finalPrice = (numItems * itemPrice)
    - min(5, numItems) * itemPrice * 0.1;

Sans commentaire :

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;

2. Extraire une méthode
Avec commentaire :

Code :

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

1
2
// Filter offensive words.
for (String word : words) { ... }

Sans commentaire :

Code :

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

filterOffensiveWords(words);

3. Utiliser un nom d'identificateur plus descriptif
Avec commentaire :

Code :

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

int width = ...; // Width in pixels.

Sans commentaire :

Code :

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

int widthInPixels = ...;

4. Ajouter un contrôle dans le cas où votre code a des hypothèses
Avec commentaire :

Code :

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

1
2
// Safe since height is always > 0.
return width / height;

Sans commentaire :

Code :

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

1
2
checkArgument(height > 0);
return width / height;

Il y a bien sûr des cas où un commentaire peut être utile. C'est le cas par exemple lorsqu'il est nécessaire de révéler votre intention, c'est-à-dire expliquer pourquoi le code fait quelque chose (ce qui est différent d'expliquer ce que fait le code). On peut, entre autres, également utiliser des commentaires pour apporter une clarification à une question qui a été soulevée lors de la revue du code ou que les lecteurs du code pourraient avoir. Dans tous les cas, les ingénieurs de Google pensent qu'il faut éviter les commentaires qui ne font que dire ce que fait le code, car ce n'est que du bruit. Par exemple :

Code :

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

1
2
3
4
// Get all users.
userService.getAllUsers();
// Check if the name is empty.
if (name.isEmpty()) { ... }

Source : Google Testing Blog

Et vous ?

Qu’en pensez-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 ?

Voir aussi :

Un code bien écrit a-t-il besoin des commentaires ? Quelle est la place des commentaires dans votre code ?
Linus Torvalds fustige des développeurs du noyau Linux pour des styles de commentaires qu'il qualifie de « dégoûtants » et visuellement déséquilibrés

[palnap]

Et vive les CheckStyles qui imposent de mettre des commentaires sur les getters & setters (et pire les langages qui imposent d'avoir des getters & setters ) et de lister tous les paramètres et retours des méthodes :

Code Java :

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

1
2
3
4
5
6
7
/**
* Retourne l'âge du capitaine.
* @return âge du capitaine
**/
public int getAgeCapitaine() {
    return ageCapitaine;
}

[Washmid]

Et vive les CheckStyles qui imposent de mettre des commentaires sur les getters & setters (et pire les langages qui imposent d'avoir des getters & setters ) et de lister tous les paramètres et retours des méthodes :

/**
* Retourne l'âge du capitaine.
* @return âge du capitaine
**/
public int getAgeCapitaine() {
return ageCapitaine;
}

/**
* Retourne l'âge du capitaine.
* @return âge du capitaine, en années ? en secondes ? en millisecondes ? peut être négatif ? peut être 0 ? sur une application multi-threadée la méthode est synchronisée ?
**/

Et pour le setter, @param ageCapitaine l'age du capitaine c'est de la paraphrase idiote, mais... il se passe quoi si tu mets un âge négatif ? une exception ? osef ça passe ? négatif est ramené à 0 ?

Si tu commences par répondre à toutes ces question (et c'est le strict minimum), tu verras que les commentaires de méthode sont indispensables dès que ton projet a une taille conséquente.

... et bien sûr qu'il faut avoir des getters setters ! Comment tu fais quand t'as un bug et que tu veux mettre un point d'arrêt parce que la valeur que tu as dans ton objet est déconnante ? tu mets des sysout partout (quand t'as accès aux sources en modif....) ?

[Bousk]

/**
* Retourne l'âge du capitaine.
* @return âge du capitaine, en années ? en secondes ? en millisecondes ? peut être négatif ? peut être 0 ? sur une application multi-threadée la méthode est synchronisée ?
**/

Et pour le setter, @param ageCapitaine l'age du capitaine c'est de la paraphrase idiote, mais... il se passe quoi si tu mets un âge négatif ? une exception ? osef ça passe ? négatif est ramené à 0 ?

Si tu commences par répondre à toutes ces question (et c'est le strict minimum), tu verras que les commentaires de méthode sont indispensables dès que ton projet a une taille conséquente.

... et bien sûr qu'il faut avoir des getters setters ! Comment tu fais quand t'as un bug et que tu veux mettre un point d'arrêt parce que la valeur que tu as dans ton objet est déconnante ? tu mets des sysout partout (quand t'as accès aux sources en modif....) ?

Ton commentaire de méthode si indispensable devient immédiatement obsolète dans ce cas avec de bonnes pratiques
- Pour lever l'ambiguité négatif ou pas : tu utilises un type non signé
- Pour lever l'ambiguité de l'unité : tu utilises un type plus spécifique comme disons Age

Si tu as une méthode process, check, qui fait vraiment des opérations, tu peux vouloir détailler ce qu'il se passe quand tu l'appelles, ce que ça implique.
Un simple getter ou setter, le commenter c'est au mieux stupide, cf ci-dessus.

[martopioche]

Et vive les CheckStyles qui imposent de mettre des commentaires sur les getters & setters (et pire les langages qui imposent d'avoir des getters & setters ) et de lister tous les paramètres et retours des méthodes :

/**
* Retourne l'âge du capitaine.
* @return âge du capitaine
**/
public int getAgeCapitaine() {
return ageCapitaine;
}

Sauf que ce n'est pas des commentaires mais de la documentation…

Et pour le setter, @param ageCapitaine l'age du capitaine c'est de la paraphrase idiote, mais... il se passe quoi si tu mets un âge négatif ? une exception ? osef ça passe ? négatif est ramené à 0 ?

Si on parle CheckStyle et getters/setters, on parle d'un langage tel que Java, donc la levée d'exception est déclarée. Et si une méthode "setAge" ne lève pas une exception pour un âge négatif ou se permet de la ramener à 0, c'est plutôt un signe qu'il faut réécrire une classe Capitaine fiable…

Et si je veux aller plus loin, je dirai que si il s'agit réellement de Java, il ne se passe rien, le paramètre si du bon type est accepté et c'est tout. La validation passe par des validateurs, classes dédiées incorporés aux CapitaineFactory…

Si tu commences par répondre à toutes ces question (et c'est le strict minimum), tu verras que les commentaires de méthode sont indispensables dès que ton projet a une taille conséquente.

Même sans qu'il ai une taille conséquente… Les méthodes, fonctions et paramètres doivent être documentés au minimum pour expliquer les limites des paramètres comme tu l'a écris.

... et bien sûr qu'il faut avoir des getters setters ! Comment tu fais quand t'as un bug et que tu veux mettre un point d'arrêt parce que la valeur que tu as dans ton objet est déconnante ? tu mets des sysout partout (quand t'as accès aux sources en modif....) ?

Tout dépend si tu écrit un code pour être mis en production ou pour être débuggué… Fondamentalement, un "setAge" du capitaine n'a aucun sens. Il suppose entre autre qu'avant d'appeler setAge, un objet de type Capitaine a été créé avec un paramètre age à Null… C'est normal ? Et quelle est la visibilité de setAge ? Publique, privée ? Si elle est publique, on est bien d'accord que ton objet Capitaine peut changer d'âge à mon bon vouloir dans mon programme ? Enfin, l'année prochaine, j'ai quoi, un capitaine qui a le même âge ou c'est à moi d'incrémenter la valeur ?
La présence des getters/setters a un grand intérêt : elle permet de déterminer qu'un code "orienté objet" a été écrit par des développeurs qui n'ont aucune notion de POO.

[martopioche]

Bonjour,
En fait j'utilise les fonctions de certains scripts de création d'aide en ligne à l'aide de commentaires.
Du coup, je décrit de manière intelligible ce que fait tel ou tel fonction, les paramètres, les entrée, les sortie, etc.

Ce n'est pas du commentaire mais de la documentation

La seule exception, c'est lorsque la fonction (souvent Main) est divisée en plusieurs étapes, alors je les nommes avec des commentaires, qui sont souvent suivies par un appel de fonction quasi identique.

Donc c'est du bruit inutile.

Après, c'est comme pour beaucoup de chose, les goûts et les couleurs c'est perso.

C'est ce dont veulent se convaincre ceux qui ne se soucient pas de la qualité de leur code. Dans le cas particulier des commentaires, que ce soit perso ou non, un commentaire est du bruit, le bruit ne sert qu'à gêner quelqu'un et ici celui qui relis le code. Un commentaire est censé être un signal "attention, le code suivant ne parle pas de lui même". Quand c'est le cas, on perd du temps à chercher qu'est ce qu'on n'a pas compris dans le commentaire. Toutes les études sur le sujet ont montré ce type de comportement.

1 - Pour lever l'ambiguité négatif ou pas : tu utilises un type non signé
2 - Pour lever l'ambiguité de l'unité : tu utilises un type plus spécifique comme disons Age

Pas tout à fait d'accord :
1 - les types non signés n'existent pas dans tous les langages, mais de toutes manières, ils ne borneront que la valeur minimum. Un capitaine de 800 ans a-t-il un sens en supposant qu'il ne peut être un Jedi ? Un capitaine de 5 ans ?
2 - est-il réellement besoin de créer un type pour représenter un entier ??? Surtout que dans ce cas précis, la valeur l'âge est lié au métier (ex: agences de voyage)

De toutes manières, ces réponses sortaient de la notion de commentaire pour aborder celui de la documentation, une documentation qui ne décrit pas les paramètres montre juste que la lib est à jeter.

[evanboissonnot]

Bonjour

Très intéressant de relancer le débat.

Il est encore bien courant pour des enseignants de transmettre l'une des plus grandes erreurs selon moi : commenter son code.

Commenter son code, c'est permettre qu'il ne soit pas lisible.
C'est pourquoi dans mon entreprise, j'ai interdit les commentaires de code, avec deux exceptions :

- les commentaires publics (commentaires de méthodes, pour la doc auto-générée)
- les commentaires sur un code non améliorable (exemple, dans une procédure stockée, où la lisibilité du code peut empêcher l'optimisation d'une requête)

C'est un très bon principe et je pense qu'il faut l'enseigner à tout le monde.

A bientôt
Evan

[CaptainDangeax]

ça me rappelle mon stage de fins d'études à l'IUT, en 1990 : débugguer la ROM d'un terminal qui avait les caractéristiques suivantes : µC Intel 8031, connexion par boucle de courant RS485, Afficheur LCD 2x40 caractères, clavier alphanumérique, lecteur de badges magnétique, module PIO. Toutes les fonctions gérant les E/S fonctionnaient, mais pas l'ensemble du firmware... Le code assembleur était écrit sans commentaire et avec des fonctions au nom abscons, sans parler des variables : A1, A2, A3, à ne pas confondre avec les registres A, B, R0 à R7, DPTR, P2... Je ne connaissais même par l'existence du 8031, on n'avait vu que le 8085 (ancêtre du Z80) en cours. Merci l'éducation nationale de nous apprendre des processeurs démodés. Les 3 premiers jours, je les ai passé à isoler les fonctions et à commenter le code assembleur, sur un PC 286 en 80x25 EGA. La ROM une fois assemblé pesait 11kB, c'est gros pour du 8 bits... Jeune débutant à l'époque, j'aurais aimé des commentaires. Bon j'ai réussi la mission et j'ai eu mon DUT.
Maintenant, je nomme mes fonctions et mes variables avec des noms explicites, au moins quand elles servent au long du programme. i, j, k conviennent très bien pour des indices de boucle locaux à une fonction, on n'est pas dactylo non plus. Même si personne ne me relit, c'est plus facile même pour moi quand il faut reprendre le code plus tard.

[Cincinnatus]

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.

Si une variable intermédiaire peut remplacer avantageusement un commentaire en détaillant une opération, pourquoi s'en passer ? De toutes façons, le compilateur optimisera ton code, si c'est ça qui bloque.

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.

Même chose, le compilateur peut réduire les appels s'il l'estime possible.

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" ).

Dans leur contexte, les noms sont rarement très longs. Je préfère des termes explicites, plus faciles à relire.

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 ...

Effectivement, les deux ne sont pas exclusifs. Le commentaire précise l'intention, le code valide les hypothèses.
Dans le cas repris ensuite d'un âge de capitaine, si une donnée à une étendue précise, pourquoi ne pas créer un type vérifiant les contraintes ?

Un type AgeDuCapitaine pourrait bloquer en cas d'âge trop bas ou trop élevé et documenterait parfaitement ces contraintes.
On pourrait aussi avoir en dérivés les types AgeDuCapitaineDePedalo et AgeDuCapitaineDeLongCourrier.

Pour ceux que ça intéresse, le langage ADA est à étudier...

[Nebulix]

Il est intéressant de considérer des exemples un peu moins niais.
Soit

Code :

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

1
2
3
4
5
//data[1..d1,1..d2]
// somme des carrés
for i:=1 to d1 do
for j:=1 to d2 do
somme:=somme+sqr(data[i,j]);

ou bien

Code :

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

1
2
3
4
for indice_balayant_la_première_dimension_du_tableau_des_données:=1 to première_dimension_tableau_des_données do
for indice_balayant_la_deuxième_dimension_du_tableau_des_données:=1 to deuxième_dimension_tableau_des_données do
somme_des_carrés_des_éléments_du_tableau_des_données:=somme_des_carrés_des_éléments_du_tableau_des_données+sqr(tableau_des_données[indice_balayant_la_première_dimension_du_tableau_des_données,indice_balayant_la_deuxième_dimension_du_tableau_des_données]);

[psychadelic]

Je me suis fait les dents en C en épluchant les bouquins de Scott Knaster.
J'ai travaillé sur des bibliotheques en C et C++ sur des produits financiers devant réaliser des formules complexes sur des indices complexes avec des variables complexe ou il faut parfois plusieurs heures avant d'en comprendre le sens et le comment du pourquoi.
Alors quand t'a passé un semaine sur un swap de taux avec des conversions de monnaies fluctuantes, ben ,tes super content de retrouver un gros commentaire qui t'explique ce qu'il ne faut surtout pas tripoter et un rappel des règles qui s'y appliquent, voir même des petits rappels triviaux pour te dire que cette variable joue sur un taux directeur, même si elle s'appelle justement taux_directeur, parce que je ne connais pas un développeur capable de garder la tête froide en jonglant avec 36 formules mathématiques et financières à longueur de journée.

Et pour en revenir à Scott Knaster, je fais comme lui, je dissémine de l'humour au second degré dans mon code (mais toujours en lien avec l’algorithme, parce que je me suis rendu compte que cela faisait toujours plaisir à ceux devaient re-tripoter le code, et que s'il est placé au bon endroit cela leur permettait de mieux se souvenir des écueils à éviter.

Les exemples de codes sur le sujet , c'est du flan à coté.

[bcag2]

G19 et G20 pages 318 et 319 de «Coder proprement» de Robert C.Martin (ISBN 978-2-7440-2583-9)
… rien de nouveau

[Jarodd]

Ou sinon :

https://github.com/ryanmcdermott/clean-code-javascript

(ça ne s'applique pas qu'au js)

[michel.bosseaux]

Tout à fait d'accord.
Les commentaires sont le plus souvent inutiles, sauf quand la personne qui va reprendre le code est un vrai débutant (quand on donne cours par exemple), où là, on n'en met jamais assez ^^

[transgohan]

Je serai mitigé pour ma part...
J'aurai tendance à dire que mettre des commentaires partout est inutile mais à côté de cela je travaille sur du code très gros et très complexe et sans les commentaires inutiles cela devient une galère monstrueuse pour trouver rapidement ce que l'on cherche par simple méconnaissance du code concerné...

[martopioche]

je travaille sur du code très gros et très complexe et sans les commentaires inutiles cela devient une galère monstrueuse pour trouver rapidement ce que l'on cherche par simple méconnaissance du code concerné...

Peut-être justement parce qu'il est maintenu dans un état "complexe"… D'expérience, ce type de remarque concerne toujours du code où on ne comprends rien aux noms des variables, où tout est écrit de manière procédurale et la compréhension nécessite de lire chaque ligne. Le bon sens présenté ici est de remettre en évidence que fonctions et variables ont des noms et que du code peut être déporté dans une fonction pour en expliquer l'intention.

[transgohan]

Peut-être justement parce qu'il est maintenu dans un état "complexe"… D'expérience, ce type de remarque concerne toujours du code où on ne comprends rien aux noms des variables, où tout est écrit de manière procédurale et la compréhension nécessite de lire chaque ligne. Le bon sens présenté ici est de remettre en évidence que fonctions et variables ont des noms et que du code peut être déporté dans une fonction pour en expliquer l'intention.

Les variables sont très bien nommées, le code en lui même n'est pas forcement complexe, mais le système l'est.
De par cela le code le devient car pour faire la moindre chose il y a des interconnexions avec d'autres modules voir d'autres composants électronique.
Rajoutes de l'asynchronisme et du temps réel dedans et tu obtiens un sacré beau bordel pour un non initié.
Quand je suis arrivé sur le projet j'ai mis un mois pour corriger le premier ticket ouvert qu'on m'a attribué...
Bon nombre de bug nécessitent 3-4 jours de lecture et de tests pour finalement rajouter une condition. Je t'explique pas à combien tourne notre indicateur de temps passé / ligne de code.

De plus la quantité de code rend les choses difficilement mémorisable, on se souvient peu de la partie qu'on a débuggué il y a 2ans...
Le code est tellement gros qu'une équipe de dix personnes peut passer 3ans sans intervenir sur un module... Du coup quand on s'y replonge c'est pas simple. Tout commentaire est bon à prendre pour se balader dedans.

[palnap]

Les variables sont très bien nommées, le code en lui même n'est pas forcement complexe, mais le système l'est.
De par cela le code le devient car pour faire la moindre chose il y a des interconnexions avec d'autres modules voir d'autres composants électronique.

Peut être que ça nécessiterait un peu de refactoring dans ce cas. Des tâches trop complexes peuvent toujours être divisées en un ensemble de tâches plus simples.

[sirthie]

Tout à fait d'accord.
Les commentaires sont le plus souvent inutiles, sauf quand la personne qui va reprendre le code est un vrai débutant (quand on donne cours par exemple), où là, on n'en met jamais assez ^^

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

[foetus]

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 ?

C'est sûr si tu pars du postulat "un commentaire ne sera mis à jour", autant rien commenter
Et dans ce cas travailler directement sur le code: nom de variables plus explicite, découper les fonctions au risque d'avoir plus d'appels non optimisables, du code plus long parce qu'on rajoute des variables temporaires, ...

L'idée des 30 ans, c'est du code qui a vécu (maintenu/ mis en production / refactorisé/ ...).
Et que si dès le départ, le code est commenté et que l'équipe de développement a été rigoureuse sur la mise à jour des commentaires, tu es bien content de les avoir au bout 30 ans.
Il me semble qu'il y a 30 ans il n'y avait pas de système de gestion de configurations, qui est utile aussi pour un historique.

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

Et je tiens à préciser une chose: un commentaire ne doit pas être descriptif, sauf cas très particulier
C'est pour cela que je l'utilise pour décrire les formules mathématiques (par exemple), pour garder du code mort, pour marquer du code, pour alerter d'une chose (XXX), ...
Et comme il n'est pas descriptif, s'il n'est pas mis à jour, c'est moins grave (sauf éventuellement quelques alertes).

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 ?

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

Par exemple, je vois que dans le développement Web, lorsqu'on commit du code, il est analysé (JSLint), il est testé, voir plus, ...

En C++, des fois tu n'as qu'un compilateur. Moi, je travaillais sans système de gestion de configurations, et les quelques tests étaient manuels.
Donc, oui c'est dangereux de retirer/ remettre du code à la main (essentiellement pour tester/ déboguer), mais des fois tu es obligé.
D'où l'utilisation des commentaires pour faciliter les manœuvres.

Il y aurait une autre solution: la conception. Par exemple, intégrer un système de log (fichiers et réseau) et qu'on puisse l'activer à la ligne de commande.
Le problème, c'est que cela demande du temps

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

Et encore plus (<- Dupont ) on peut extraire une partie du code pour un autre projet.