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

Le , par Michael Guilloux, Chroniqueur Actualité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
1
2
3
// Subtract discount from price.
finalPrice = (numItems * itemPrice)
    - min(5, numItems) * itemPrice * 0.1;
Sans commentaire :
Code : Sélectionner tout
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
1
2
// Filter offensive words.
for (String word : words) { ... }
Sans commentaire :
Code : Sélectionner tout
filterOffensiveWords(words);

3. Utiliser un nom d'identificateur plus descriptif
Avec commentaire :
Code : Sélectionner tout
int width = ...; // Width in pixels.
Sans commentaire :
Code : Sélectionner tout
int widthInPixels = ...;

4. Ajouter un contrôle dans le cas où votre code a des hypothèses
Avec commentaire :
Code : Sélectionner tout
1
2
// Safe since height is always > 0.
return width / height;
Sans commentaire :
Code : Sélectionner tout
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
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


Vous avez aimé cette actualité ? Alors partagez-la avec vos amis en cliquant sur les boutons ci-dessous :


 Poster une réponse

Avatar de palnap palnap - Membre actif https://www.developpez.com
le 19/07/2017 à 12:10
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;
}
Avatar de bcag2 bcag2 - Membre régulier https://www.developpez.com
le 19/07/2017 à 12:19
G19 et G20 pages 318 et 319 de «Coder proprement» de Robert C.Martin (ISBN 978-2-7440-2583-9)
… rien de nouveau
Avatar de Jarodd Jarodd - Membre expérimenté https://www.developpez.com
le 19/07/2017 à 13:01
Ou sinon :

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

(ça ne s'applique pas qu'au js)
Avatar de michel.bosseaux michel.bosseaux - Membre averti https://www.developpez.com
le 19/07/2017 à 13:06
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 ^^
Avatar de transgohan transgohan - Expert confirmé https://www.developpez.com
le 19/07/2017 à 13:43
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é...
Avatar de martopioche martopioche - Membre confirmé https://www.developpez.com
le 19/07/2017 à 13:48
Que du bon sens qui sont déjà les principes qui devraient être suivis…*Mais l'article apporte des exemples intéressants
Avatar de Oscar.STEFANINI Oscar.STEFANINI - Membre régulier https://www.developpez.com
le 19/07/2017 à 13:49
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/
Avatar de Sange844 Sange844 - Nouveau membre du Club https://www.developpez.com
le 19/07/2017 à 13:54
Une référence additionnelle à celles déjà citées:

Jeff Atwood: Code Tells You How, Comments Tell You Why
Avatar de BugFactory BugFactory - Membre éprouvé https://www.developpez.com
le 19/07/2017 à 13:55
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.
Avatar de martopioche martopioche - Membre confirmé https://www.developpez.com
le 19/07/2017 à 14:05
Citation Envoyé par transgohan Voir le message
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.
Offres d'emploi IT
Développeur logiciel embarqué h/f
Atos - Ile de France - Boulogne-Billancourt (92100)
Lead Developer PHP5
PICKTURE - Ile de France - Paris (75003)
Technicien support applicatif h/f
PRECICAP - Ile de France - Boulogne-Billancourt (92100)

Voir plus d'offres Voir la carte des offres IT
Contacter le responsable de la rubrique Accueil