Discussion :

[Malick]

Bonjour,
à mon avis, il est toujours bon de commenter les codes; ceci aidera les tiers personnes (surtout les débutants) à comprendre sans trop de difficultés.

[koala01]

Bonjour,
à mon avis, il est toujours bon de commenter les codes; ceci aidera les tiers personnes (surtout les débutants) à comprendre sans trop de difficultés.

Si ton code est à visée pédagogique (comprends : qu'il est écrit pour justement permettre à un débutant d'apprendre le langage ou la programmation en générale), ton argument tient la route.

Mais, dans un code de production, on est malgré tout en droit d'attendre de la part d'un développeur qu'il connaisse "un minimum" le langage avec lequel il travaille ou, à défaut, qu'il soit "un minimum en mesure" de faire le parallèle avec un langage qu'il connaît.

A partir de ce point, on peut se demander ce qu'un commentaire apporte par rapport au code, et le problème devient la pérennité du commentaire par rapport au code.

Si le commentaire permet réellement de comprendre une idée qui n'apparaît pas clairement au travers de ton code, c'est sans doute que le code lui-même devrait être revu, en choisissant des noms de variables, de types et de fonction plus explicites, ce qui nous fait, de facto, tomber dans le cas suivant.

Si le commentaire n'apporte rien de plus par rapport au code, il est purement et simplement inutile et, à ce titre, il devient aussi dangereux que du code inutile car source d'erreur, surtout s'il n'est pas correctement mis à jour en même temps que le code.

Et donc, si tu veux que ton commentaire soit pérenne, il faut qu'il fournisse au lecteur une information qui sera indépendante du code en lui-même. Il faut donc qu'il explique la fonctionnalité -- en ajoutant, pourquoi pas, une aide à la décision qui permette de choisir entre deux fonctionnalités équivalentes -- plus que le moyen mis en oeuvre pour y arriver, et cela ne se fait pas dans le code lui-même: cela se fera dans un cartouche.

Je n'ai rien contre un commentaire qui prendrait la forme de

Code c++ :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/* Trie la collection selon le comparateur fourni.
 *
 * Utilise le comparateur pour effectuer un tri par insertion.
 * paramètre template Collection : le type de collection à trier.
 * paramètre template Comparateur : Le type de comparateur à
 *                                     utiliser lors du tri.
* parametre (in) collection : La collection d'objets à trier.
* précondition : Les éléments de la collection doivent être
*               copiables et comparables à l'aide du
*               comparateur indiqué.
* renvoie : Une nouvelle collection contenant les objets triés
*           dans l'ordre prescrit par le comparateur.
* nota    : La collection originale n'est pas modifiée lors du tri.
* voir aussi : Peut-être préférerez-vous la fonction triQuickSort.
*/
template <typename Collection, typename Comparateur>
Collection triParInsertion(Collection const & col,
Comparateur comparateur){
 
}

Mais je ne vois pas la moindre raison de placer un commentaire entre l'accolade ouvrante et l'accolade fermante de la fonction

[sekaijin]

...

Je n'ai rien contre un commentaire qui prendrait la forme de

Code c++ :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/* Trie la collection selon le comparateur fourni.
 *
 * Utilise le comparateur pour effectuer un tri par insertion.
 * paramètre template Collection : le type de collection à trier.
 * paramètre template Comparateur : Le type de comparateur à
 *                                     utiliser lors du tri.
* parametre (in) collection : La collection d'objets à trier.
* précondition : Les éléments de la collection doivent être
*               copiables et comparables à l'aide du
*               comparateur indiqué.
* renvoie : Une nouvelle collection contenant les objets triés
*           dans l'ordre prescrit par le comparateur.
* nota    : La collection originale n'est pas modifiée lors du tri.
* voir aussi : Peut-être préférerez-vous la fonction triQuickSort.
*/
template <typename Collection, typename Comparateur>
Collection triParInsertion(Collection const & col,
Comparateur comparateur){
 
}

Ceci c'est de la documentation de l'API pas un commentaire il devrait commencer par /** et non /*.

Code c++ :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/** 
 * Trie la collection selon le comparateur fourni.
 * Utilise le comparateur pour effectuer un tri par insertion.
 * nota    : La collection originale n'est pas modifiée lors du tri.
 * @param Collection col : La collection d'objets à trier.
 * @param Comparateur comparateur : comparateur à utiliser lors du tri.
 * @return : Une nouvelle collection contenant les objets triés dans l'ordre prescrit par le comparateur.
 * @see Peut-être préférerez-vous la fonction triQuickSort.
 */
template <typename Collection, typename Comparateur>
Collection triParInsertion(Collection const & col,
Comparateur comparateur){
 
}

A+JYT

[BlueScreenJunky]

Les IDE que j'utilise (Netbeans, phpStorm) ont besoin de commentaires phpdoc bien rédigés pour fonctionner correctement (autocomplétion, documentation dans les popups...). Donc mes codes sont tous commenté en phpdoc, avec parfois quelques commentaires en ligne supplémentaire pour les trucs que je n'ai pas réussi à faire de manière évidente et dont je me dit "si un collègue reprend ça dans un an il risque de ne pas comprendre pourquoi j'ai fait ça".

[nouknouk]

Si j'ai bien compris, le bonhomme nous explique qu'un commentaire non pertinent n'est pas pertinent, et qu'un commentaire pertinent est pertinent.

Sans commentaire.

[atha2]

Si j'ai bien compris, le bonhomme nous explique qu'un commentaire non pertinent n'est pas pertinent, et qu'un commentaire pertinent est pertinent.
Sans commentaire.

Je pense plutôt que le "bonhomme" cherche à montrer que tout les commentaires ne sont pas pertinents. Accessoirement il montre quels commentaires sont pertinents et lesquels ne le sont pas.
Quand je vois les codes/commentaires sur lesquels je tombe, j'ai envie de lui dire merci !
Bon, de mon coté j'ai tendance à ne commenter à l'intérieur des méthodes que quand la situation l’exige (algo complexe). Je ne commente les méthodes/classes seulement si elles ont vocation à être utilisées en tant qu'API ou éventuellement en attendant de trouver un nom/découpage clair (avec un TODO). Je ne vais pas perdre mon temps à ajouter des @param et autres, quand la seule lecture du nom du paramètre/méthode suffit.

[doublex]

Les commentaires, c'est comme l'éclairage sur l'autoroute. Ce n'est pas indispensable, mais ça aide.

[mabdylon]

Je suis de plus en plus pour un code sans commentaires. Ceux ci n'ont aucune valeur pour le compilateur, et du coup sont potentiellement erronés.

Je ne compte plus les commentaires effacés dans le code sur lequel je travaille, parce qu'ils deviennent tous obsolètes trop vite, ou bien simplement incompréhensibles, ... et pire encore, ils nous induisent souvent en erreur après un certain temps.

[BenoitM]

Je suis de plus en plus pour un code sans commentaires. Ceux ci n'ont aucune valeur pour le compilateur, et du coup sont potentiellement erronés.

Je ne compte plus les commentaires effacés dans le code sur lequel je travaille, parce qu'ils deviennent tous obsolètes trop vite, ou bien simplement incompréhensibles, ... et pire encore, ils nous induisent souvent en erreur après un certain temps.

Ca me fait penser à la doc d'un projet.
Mais bon plutot de dire que c'est le commentaire qui n'a pas d'utilité, je dirait que c'est celui qui met à jours le code qui est en tord.

De plus c'est bien beau de dire qu'il suffit de faire un code propre mais
1) C'est rarement le cas
2) Tu n'as pas toujours le choix
3) Perso il m'est déjà arriver de devoir reprendre du code que j'ai écrit il y a 2-3 ans, quand j'ai du le relire , j'ai été moins convaincu (bon j'ai de l'expérience en plus). Mais je ne suis pas sur que celui qui code est le mieux placer pour mettre des commentaires car quand on sait ce qu'on veut faire tout nous parrait limpide.

[jiber2fr]

Je ne suis pas du tout d'accord.

Premièrement (et ça a déjà été dit), les commentaires aident quelqu'un qui reprendrait le code à le comprendre plus facilement. A part dans un HelloWorld, les noms de variables et de méthodes ne peuvent pas être assez explicites pour se passer de commentaires. Donc, au minimum, les déclarations de variables et les entêtes de méthodes doivent être commentées.

Ensuite, concernant le commentaire dans le corps des fonctions, ils aident autant celui qui écrit le code que celui qui le reprendra un jour. C'est vrai surtout s'il s'agit d'algorithme un peu compliqué. Avant d'écrire un code compliqué, je réfléchi à l'algo, et j'écris les principales étapes de l'algo sous forme de commentaire dans le corps de ma méthode. Une fois que c'est fait, je n'ai plus besoin de réfléchir: il ne reste qu'à remplir le code entre les commentaires.

J'ai donc un raisonnement inverse à celui de cet article: pour moi, une méthode bien commentée doit pouvoir se comprendre en lisant uniquement les commentaires; on ne comprendra pas comment le code fait, mais on saura parfaitement ce qu'il fait.

[BPiero]

Dans l'absolu (vers lequel on doit se diriger), je suis super d'accord avec ce mec, il ne devrai jamais y avoir de commentaire. Si l'espace de nom, la classe, la signature de la méthode et l'organisation du code sont corrects, nul besoin de commentaire, le code parle de lui-même y compris à un débutant.
Dans la vraie vie, il en va différemment, car il arrive toujours un moment où le choix d'un nom n'est pas évident (et on a pas le temps de trouver un truc nickel), où pour aller plus vite on écrit un algo difficile à déchiffrer, des lignes trop longues, et des paramètres équivoques ou polyvalents. Dans ces cas là, les commentaires sont nécessaires. A fortiori si il s'agit d'interfaces, ou de méthodes publiques.
Notez que le "pourquoi" d'un code peu également être explicité par son fichier de test unitaire (encore un argument qui confirme que le TDD est une bonne pratique).

[Invité]

Trop simple.
1. Commente-t-on uniquement un code parce qu'on pense qu'il faut "toujours" commenter un code ?

Commente-t-on un code pour pouvoir le relire ou pour permettre aux autres de le relire ? Et la question corolaire :
Supprime-t-on les commentaires d'un code pour le protéger contre la relecture par des yeux indélicats ?
Quid des obfuscateurs ?
Quid des noms de variables "auto-documentées" qui occupent 40 caractères à force de leur ajouter des préfixes et des suffixes alors que ladite variable s'appelle déjà "RésultatBoucleAprèsSuppressionDesDoublons"
Pourquoi utilise-t-on des acronymes comme EOF, CRLF, ASCII ? Doit-on se limiter aux acronymes historiques ou peut-on en créer de nouveaux en fonction des notions manipulées par le programme et dans ce cas, où peut-on documenter ces nouveaux acronymes ?

autres considérations :
Dois-je commenter du javascript ? Doisje mettre des noms de variables explicites en javascript ?
Pire :
Quand je fais un portage entre du php et du C# , dois-je modifier les noms de variables puisque l'un est précompilé et l'autre non ?

Difficile alors de donner une opinion expéditive sur cette question. Un beau code est à la fois facile à lire et légèrement commenté il me semble. Pour l'éducation, les commentaires mettront l'accent sur les points étudiés.
En production dans une grande équipe , on commente pour des professionnels supposés formés.. En solitaire free-lance on évite de produire un code trop facile à lire car on craint qu'un développeur peu expérimenté jouissant de tous les droits chez le client vienne modifier le code et y introduire des bugs de débutant aussi ....

Tout cela me fait penser que les situations peuvent être très différentes et que les personnes qui lisent votre code ne sont pas nécéssairement bien inspirées à l'égard de votre travail . Bien entendu, le contraire est non seulement possible mais hautement souhaitable et un développeur trop parano risque de s'attirer des remarques désobligeantes qui justifieront sa future parano et ainsi de suite..

Ensuite , il y a ces languages très optimisables comme le C où on peut recourir à des syntaxes absolument illisibles pour des raisons de performance (liste chainée de pointeurs sur pointeurs sur fonctions...)

Est ce que cette page est uniquement réservée à des étudiants ou des gens qui ne jurent que par le code ouvert ?

Finalement , si vous etes en confiance et que les gens qui vous entourent méritent cette confiance , commentez régulièrement car , on peut parcourir le code uniquement en lisant les commentaires pour s'arréter exactement là où on a une modif à faire - modif qui sera datée et signée dans un commentaire ...

[StefGac]

Je suis d'accord avec l'article dans le sens qu'un commentaire n'est pas une paraphrase du code( cf la partie extrait(), load() etc ..)
Par contre, en relisant du code, combien ai-je pu râler ou perdu de temps à comprendre le POURQUOI et non le COMMENT.
J'aurais préféré dans le code parfois un commentaire qui explique un choix d'un algorithme ou d'une implémentation comme, par exemple en java, une ArrayList au lieu d'une LinkedList ( et y'en a d'autre; cet exemple n'est pas à prendre au pied de la lettre)
J'ai pu constater aussi qu'en absence d'explication sur le pourquoi, on se retrouve avec du code dit "historique" avec lequel personne ne veux prendre de décision. Parfois aussi ne comprenant pas les raisons à l'époque de l'implémentation, on casse un code qui fonctionne pour des raisons bien particulières.
Un commentaire devrait aussi indiquer des numéro de bug pour des fix.
En conclusion, des commentaires, oui, mais qui explique le pourquoi. Encore faut il que le développeur joue le jeu : l'information n'est elle pas une source de pouvoir ?

[olivier2013]

Un bon code doit, selon moi, avoir des commentaires fonctionnels ayant un apport supplémentaire.

Il est évident que du commentaire basique décrivant le code n'est pas intéressant.

[moldavi]

Bonjour.

Je suis très controversé sur les commentaires. Je trouve cela très utile et très chiant.

Quand je découvre un code écrit par une autre personne, c'est sympa d'avoir des commentaires de partout. Ca évite parfois de lire 15 pages de specification

Par contre quand je code, les commentaires c'est gonflant. Il y a du vert de partout, une fonction de 20 lignes en fait 50, le cadre de travail est exécrable. Il faut scroller sur deux/trois pages, on ne peut pas avoir une vision d'ensemble correcte sur la fonction. Bref c'est comme le code trop aéré, selon moi, tout cela nuit à une bonne maintenance du code. Si on débuge une fonction qui tiens sur l'écran, ce sera plus facile de trouver l'erreur que dans le cas ou il faut scroller et re-scroller et re... A moins d'avoir une mémoire d'einstein.

Je ne vous parle même pas des projets qui contiennent des fonctions de 100 lignes de code avec 10/15 accolades ouvrantes. Rajouter des commentaires là-dessus, et c'est du grand n'importe quoi. Vous passez plus votre vie à scroller qu'à programmer.

Donc je suis mitigé.

Pour la lecture d'un code inconnu, les commentaires, c'est bien.

Quand on code, on sait ce que l'on fait. Donc commenter ce que l'on fait, ça fait doublon sur le coup. Personnellement, lorsque je code, j'ai aussi hâte de voir le résultat. Parce que commenter un code que je vais modifier 50 fois, donc recommenter 50 fois... J'exagère, mais quand vous codez tous les jours, ça prends des proportions énormes.

Bref, comment conjurer ces deux aspects.

Pour ma part :

un code le plus simple possible. Des nommages explicites et peu de commentaires.
A côté de cela, je fournis un schéma architectural du projet lorsqu'il est stable (cela permet d'avoir une vision d'ensemble du projet. Je pense que c'est mieux qu'un roman de spécification, qui sera plutôt dédié au concepteur de bibliothèque).
Lorsque j'ai le temps, je fournis un schéma fonctionnel, histoire d'entrer un peu plus dans les détails du projet.

Tout cela pour dire que les schémas/diagramme me sont beaucoup plus utiles que du roman/commentaire, lorsque je dois reprendre du code.

Mais chacun sa méthode. S'il y avait une méthode universelle, on ne sera pas là à épiloguer sur les commentaires.

L'idéal serait d'avoir un code commenté entièrement, et un code sans commentaire. L'un pour la lecture et la découverte, l'autre pour la maintenance et le débugage. Un IDE du futur quoi.

[skypers]

Les commentaires sont importants. Dire que si un code a besoin de commentaire, c’est qu’il faut changer le code lui-même, c’est très con. Certaines lignes de hack ou hardware peuvent nécessiter des explications, exemple très simple l’isqrt de Carmack.

[Jérôme_C]

À lire toutes ces réponses j'en conclus, que quelque soit la durée de vie du code, quelque soit le développeur :
- Il existe toujours un document de spécification, accessible, qui correspond exactement à ce que fais le programme, et dont la spécification pour le code examiné est identifiable aisément.
- Toutes les subtilités du langage de programmation utilisé sont parfaitement connues.
- Tous les algorithmes, pourvus qu'ils soient identifiés, son parfaitement connus.
- Toutes les API utilisées sont parfaitement connues, dans toutes les versions.

Donc de toute manière, le commentaire ne sert à pas grand chose, tout développeur code de manière suffisamment claire. En fait si quelqu'un fait remarquer qu'un commentaire aurait été utile pour telle ligne de code, RTFM, ou va te former ?

Or un code est fait pour rester en vie quelques années, alors même que :
- telle API n'est plus à la mode
- tel algorithme était super connu par le développeur, mais en fait très spécifique et trouvable que dans un ouvrage inconnu du développeur lambda
- un bug a entrainé la correction du code pour que cela fonctionne dans tous les cas, sans que la spécification en soit changée.
- le développeur n'est pas un spécialiste du langage utilisé, et il existe une meilleure solution que le code existant (et inversement)

En plus, dire que le bon code n'a pas besoin de commentaire, c'est être présomptueux et déclarer que c'est forcément le bon choix de programmation qui a été fait. Or nous ne sommes jamais à l'abri d'une erreur, ou d'une ignorance.

[air-dex]

Un bon code doit être compris avec un minimum de commentaires. Des noms suffisamment explicites pour les variables, classes, méthodes, fonctions, etc. peuvent déjà en éviter pas mal. Et puis tant pis si des fois ces noms sont un peu longs. Au pire un bon IDE/éditeur a toujours une fonction d'autocomplétion type "CTRL + Espace" pour compléter rapidement le nom à rallonge en question.

Me concernant, j'utilise les commentaires pour décrire les grandes étapes de mon code avec un résumé au début de chaque grosse partie pour expliquer ladite partie. Je suis d'accord que certaines grosses parties de codes peuvent être remplacées par des fonctions ou méthodes mais à beaucoup trop morceler le code, on perd en compréhension.

J'en mets également à certains endroits pour expliquer par exemple que tel ou tel choix peut-être dû à un bug qu'il a fallu fixer avec cette solution particulière : "J'ai fait comme ci plutôt que comme ça sinon il y a tel bug qui se produit". Un genre de "Faut pas toucher à cette partie sinon ça marche plus", mais avec la raison pour laquelle ça ne marcherait pas. Comme par exemple un workaround autour d'un bug (non résolu) d'une librairie (ça m'est déjà arrivé).

Je pense aussi que maintenir les commentaires à jour au fur et à mesure des modifications du code est une bonne pratique qui se doit d'être respectée. Les commentaires indiquent les choses qui se passent, pas celles qui se sont passées par le passé et qui ne se passent plus dans le présent. C'est bête à dire mais encore faut-il le rappeler.

[zigmo]

Pour moi les commentaires sont indispensables, à la fois dans l'en-tête d'une méthode et dans son implémentation.

Même si tous les symboles doivent être explicites et le code doit se comprendre facilement, un commentaire est forcément beaucoup plus riche et facilite la compréhension en permettant un angle de vue différent, plus détaillé ou plus global.

Ensuite et surtout commenter c'est se relire et s'interroger sur son code.

[s4mk1ng]

Il n'est peut être pas nécessaire d'oposser les deux, on peut remplacer un bon nombre de commentaires par un bon nommage explicite des variables et fonctions. Après cela ne dispense pas de faire des commentaires pour les parties compliquées du code.