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;
}

[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]

Que du bon sens qui sont déjà les principes qui devraient être suivis…*Mais l'article apporte des exemples intéressants

[Oscar.STEFANINI]

Je classe les commentaires dans tout ce qui permet d'informer quelqu'un sur une partie du code. Si ils existent et servent à faciliter la compréhension, c'est pas pour rien ! Et ce n'est pas parce que trop en mettre peut relever d'une mauvaise pratique qu'il ne faut pas en mettre !

Dans les solutions proposés, il y en a une que je n'apprecie guère, celle qui consiste à vérifier les arguments d'une fonction à l'intérieur de celle ci. C'est completement contextuel pour moi. Certaines fonctions, logiquement pensées font différentes choses à certains moments. Il n'est pas toujours évident d'avoir un ensemble de paramètre dans un état consistant, selon ce que fait la fonction. Mais la plupart du temps, avoir un "contrat" entre une fonction et celui qui l'appelle, fonctionne bien. Contrat établit par une bonne documentation, qui peut être doublée par un commentaire (d'apres moi)

Excellent article sur la programmation par contrat, sur ce meme site:

http://luc-hermitte.developpez.com/t...n-peu-theorie/

[Sange844]

Une référence additionnelle à celles déjà citées:

Jeff Atwood: Code Tells You How, Comments Tell You Why

[BugFactory]

Un autre conseil : penser à son public. Mon code est souvent lu par des stagiaires. Dans ce cas, le conseil d'éviter les commentaires évident n'est pas valable : pour un débutant, rien n'est évident. Je profite des commentaires pour signaler les designs pattern, etc. Ça évite qu'ils ne saccagent l'architecture pour résoudre un ticket.

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

[Aurelien.Regat-Barrel]

Les commentaires qui expliquent ce que font le code sont rarement une bonne chose. Mais sur du code complexe ou ancien (qui a été réécrit / optimisé / débogué plusieurs fois), ils sont très utiles pour clarifier le contexte ou l'historique du code,
en particulier expliquer ce que le code ne fait pas et pourquoi c'est ainsi.

Jetez juste un oeil au source de Linux ou Chromium pour vous convaincre.

[martopioche]

Un autre conseil : penser à son public. Mon code est souvent lu par des stagiaires. Dans ce cas, le conseil d'éviter les commentaires évident n'est pas valable : pour un débutant, rien n'est évident. Je profite des commentaires pour signaler les designs pattern, etc. Ça évite qu'ils ne saccagent l'architecture pour résoudre un ticket.

Si il y a saccage d'une architecture du fait d'un ticket, j'appelle ça une erreur de staffing…

[hotcryx]

Les commentaires ça sert à rien, c'est pas compilé (troll off)

[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....) ?

[aepli]

Bonjour,

Pour ma part je fait beaucoup de bruit ^^.

Il peut y avoir des commentaires inutiles, mais la plus part du temps ce n'est pas le cas.
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.

Par contre à l'intérieur du code, il y a très peu de commentaires, seul les cas particuliers sont expliqués ou les manières d'utiliser tel ou tel API, lorsque j'ai croché pour l'implémentation.

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.

C'est plus par flemme que ces commentaires restent présent, car j'ai de plus en plus tendance à écrire en premier les commentaires et créant ainsi une sorte de squelette que je complète par la suite avec du code.

Le publique visé, c'est en règle général, moi ...
Et cela me permet fréquemment de reprendre un bout de code rapidement sans me torture la tête avec le contenu du code ...

Par contre, quand je me rend compte qu'un code est excessivement réutilisé, je me force à en faire une bibliothèque, puis à mettre à jour mes programmes où j'utilisais ce code.

Après, c'est comme pour beaucoup de chose, les goûts et les couleurs c'est perso.
Avec la nuance suivante, si le code doit être relu par soit-même ou par autrui, il faut faire en sorte que cela soit possible.
Que se soit avec des commentaires, du code explicite ou les deux.

Et ne pas oublier d'essayer de s’améliorer avec le temps (comme les bons vins). ^^

Salutations.

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

[jopopmk]

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

À 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 ?

Dans mon cas :
- plus ou moins tout ce qui se trouve dans les headers (fonctions, globales, structs, enums), c'est ce que les dev voient de mes bilbi, ça remplace la doc
- coté code, certains algo un peu long ont des commentaires pour comprendre facilement le keskekoi -et également se repérer, certaines fonctions en C pouvant être trèèèèès longues. Il m'arrive également parfois de pondre un algo en commençant par écrire les commentaires, mais c'est très rares qu'ils restent tels quels.

Bon après-m' à tous

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