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; |
| 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) { ... } |
| 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.
| 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; |
| 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()) { ... } |
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 
) et de lister tous les paramètres et retours des méthodes :
Envoyé par jopopmk
