Discussion :

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

[slhOverFlow]

c'est évident que la présence des deux est la meuilleur chose !
mais si on exige une seul !
alors
si c'est un bon developpeur qui va lire le code, un bon code suffira.
sinon n'hésiter pas à ecrire des lettres intraCodes !

[Jarodd]

Code :

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

1
2
3
4
//Extraire les données de l’ancien système
//Transformer les données
//Charger les données dans le nouveau système

Code :

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

1
2
3
4
Extract();
Transform();
Load();

Euh, je suis désolé mais le nom de ces fonctions ne reflêtent pas du tout leurs utilisation décrite dans les commentaires.

Load() ça charge, mais ça charge quoi ? Ah ok, les données dans le nouveau système. Et si je dois écrire une fonction qui charge les données dans l'ancien système, je la nomme comment ? Load2() ? LoadOld() ?

Transform() c'est aussi extrêment précis on comprend de suite de quoi il s'agit : on transforme ! Et on peut la réutiliser dans d'autres programmes, par exemple pour transformer des patates en purée ! Il n'y a plus qu'à espérer que le code soit le même que pour transformer une donnée en autre chose, puisque c'est ce code qui nous servira à comprendre le but de la fonction !

Bref c'est peut-être vrai qu'on peut se passer de commentaires. Mais les exemples sont très mal choisis, et pas convaincants du tout. Quel est l'avantage, au final, de s'en passer ? On va économiser 50 lignes sur un fichiers de plusieurs centaines, trop bien on cva économiser un scroll de la molette Si au moins on diminuait le temps d'exécution du code, mais même pas... Par contre on risque de compliquer la lecture du code ! Je préfère ligne 2 lignes m'expliquant à quoi sert une fonction que me taper les 50 du corps de la fonction !

[ClaudeBg]

Salut
-----

Je n'envisage pas un code non commenté, déjà pour les raisons suivantes :

1) Je sais programmer et je sais ce que j'ai programmé. Pourtant quand je relis un ancien programme je suis bien heureux de trouver des commentaires. Ce qui semble évident aujourd'hui ne le sera pas forcément demain.

2) Les commentaires ne coûtent rien et n'allongent pas la durée d'exécution, donc on ne gagne rien en n'en mettant pas

3) L'argument consistant à dire qu'on perd du temps en écrivant des commentaires est une farce : personne n'utilise 100% de son temps à taper du code (il y a un temps de réflexion), et on réfléchit aussi en tapant ses commentaires, voire on s'aperçoit en expliquant ce qu'on a fait qu'il y avait moyen de faire plus simple et plus évident

4) La majorité de ceux prétendant que les commentaires sont inutiles sont les mêmes que ceux qui prétendent qu'établir d'avance le schéma de son programme (pseudo-code, ordinogramme etc) est inutile. Et, de ma propre expérience, ce sont justement ceux-là qui crient au secours en envoyant à debugger des codes illisibles et dépourvus de commentaires. Pour moi, quand je reçois une demande d'assistance avec absence de commentaires, c'est poubelle direct

5) Ceux qui trouvent les commentaires des autres inutiles n'ont simplement qu'à ne pas les lire. Par contre, ceux qui les trouvent utiles ne peuvent pas lire ceux qui ne sont pas présents. Donc, sauf si on est certain que son code ne sera jamais lu par d'autres, il faut au minimum avoir une démarche ouverte.

6) Pour moi, je suis de l'avis diamétralement opposé à celui de l'auteur de l'article. Lui prétend qu'un code suffit pour retrouver les commentaires, et moi j'affirme qu'on doit pouvoir ré-écrire le code à partir des commentaires, si ceux-ci sont bien réalisés. Même un programmeur averti lit et comprend plus efficacement sa langue natale qu'un langage informatique.

7) Les affirmations sont beaucoup trop généralistes à mon avis: Si on peut admettre la pauvreté (pas l'absence) des commentaires dans un langage proche de la syntaxe humaine (genre C#-> Linq), je défie les meilleurs programmeurs de s'y retrouver de façon "naturelle" dans les langages bas niveaux, surtout lorsqu'il s'agit de fonctions manipulant les données de façon complexes (algos mathématiques, conversions, etc).

Ma conclusion est qu'un commentaire inutile ne dérange personne et n'induit aucune perte de performance. Par contre, un commentaire absent peut se révéler dérangeant. On peut donc décider de ne pas commenter, mais conseiller de ne pas le faire est une absurdité monumentale car ce conseil loufoque ne manquera pas d'être pris pour argent comptant par ceux, justement, qui ont le plus intérêt à commenter: les débutants.

A+
Claude

[a028762]

Même si la question a été débattue depuis très longtemps.
Déjà les noms de variables et de fonctions et de classes qui causent
En générale les fonctions sont des verbes suivis d'attributs (ImprimerFacture par exemple).
et la deuxième partie de la page, col 70, un commentaire par ligne (quasiment 90%);
"évidemment", en évitant de redire la même chose ...
Cela me permet de relire le code d'il y a 6 mois et de le partager ...
Olivier

[LSMetag]

Entièrement d'accord.

A mes yeux, les commentaires devraient se limiter à la définition des méthodes, variables,...

D'autant que ces commentaires là peuvent être générés automatiquement si on nomme bien les méthodes/variables et qu'on configure en amont le plugin concerné. Ca permettrait d'éviter aux devs d'écrire des commentaires inintelligibles, quand ils prennent le temps de les écrire évidemment.

C'est pour ça que quand je code, j'essaie toujours de réduire le nombre de lignes au minimum, ce qui permet de réduire également la quantité de commentaires, qui finalement réduisent la lisibilité du code si trop nombreux.

Si c'est touffu, ça fera d'office ch... le développeur qui reprendra le code et qui sera dès le début dans de mauvaises dispositions. Il vaut mieux mettre un commentaire pour dire la finalité de l'algorithme ou encore pour les sections délicates. Mais sinon, le développeur est normalement intelligent.

Le dernier code dont je me suis occupé, j'ai par exemple fait passer le nombre de lignes de 12000 (très commentées) à 1000 (peu commentées). Tout le monde s'en porte mieux. Moins de bugs, plus faciles à corriger, et même plus performant.

[Nathanael Marchand]

D'autant que ces commentaires là peuvent être générés automatiquement si on nomme bien les méthodes/variables et qu'on configure en amont le plugin concerné. Ca permettrait d'éviter aux devs d'écrire des commentaires inintelligibles, quand ils prennent le temps de les écrire évidemment.

Voilà bien souvent ce qu'est un commentaire autogénéré :

Code :

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

1
2
3
4
5
6
7
8
/// <summary>
/// Update the scores
/// </summary>
/// <param name="scores">The new scores</param>
private void UpdateScores(IEnumerable<Score> scores)
{
	//blabla implem
}

Ce genre de commentaires, je le vire

[satenske]

Personnellement, je pense que les commentaires, c'est comme le café, faut savoir les doser. Pas assez, ça n'a pas de gout, c'est mauvais. Trop, ben on a du mal à digérer tout ça.

Donc, je pense que déjà, commenter ses fonctions avec du doxygen/javadoc, rien que ça me parrait indispensable, ça permet d'une part d'intégrer la doc à eclipse/Netbeans, d'autre part, on sait à quoi sert la fonction. Après, j'aime bien découper au maximum mon programme effectivement, if(test == truc && machin == chose || (chouette && !test)), ben autant avoir une simple fonction faisant un return de l'expression booleenne, on lui donne un nom clair et on s'epargne le commentaire.

Autre problème que je trouve aux commentaires. Le code évolue. les commentaires eux ne suivent pas systématiquement le code. Et tomber sur un commentaire qui est trompeur, y'a rien de pire.

Donc, il faut en mettre parce que ça fait toujours plaisir, mais faut doser le tout :-)

[martopioche]

faut-il réellement relancer un nième pseudo-débat sur les commentaires ?

tout cela en allant pêcher un blog de octobre 2010 !

C'est exactement ce que je me disais en voyant le titre de la news...

En 3 mots mon opinion basé sur quelques années d'expérience : L'approche "les commentaires sont inutiles, le code doit s'exprimer de lui même" n'a jamais marché, on perd plus de temps à comprendre ce qui a été écrit que de le réutiliser. Un nom de fonctions "parlant" ne "dit" pas comment la fonction se comporte (quelles sont les limites des arguments, que se passe-t-il en dehors...). Oui, il y a de fortes chances que le commentaire ne soit pas synchro avec le code, là on doit pouvoir se référer aux tests unitaires. Dans la pratique, c'est ce qui me fait apprécier les doctests en Python.

[LSMetag]

Voilà bien souvent ce qu'est un commentaire autogénéré :

Code :

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

1
2
3
4
5
6
7
8
/// <summary>
/// Update the scores
/// </summary>
/// <param name="scores">The new scores</param>
private void UpdateScores(IEnumerable<Score> scores)
{
	//blabla implem
}

Ce genre de commentaires, je le vire

Comme je dis ça dépends. Mais faire un ghostdoc sur tout le projet, pour ensuite retoucher ce qui a besoin de l'être, c'est beaucoup plus aisé pour un développeur. D'une part, ça lui permet de créer une réutilisabilité dans le code (y a rien de pire à mes yeux que ne pas avoir de JavaDoc ou équivalent quand on reprend un programme (même si elle est triviale)). D'autre part, la structure est la, et le développeur n'a plus qu'à adapter pour certains morceaux de code.

A part quand c'était des stagiaires, le code que j'ai dû reprendre brillait à tous les coups par sa quasi-absence de commentaires. Et quand le projet fait 3500 jours hommes, qu'il n'a aucun commentaires, que tu ne peux pas débugguer (pas de licence pour déployer en local), qu'en plus l'IDE ne t'aide pas (je passe mon temps à tatonner avec des CTRL+H) et que tu dois corriger le bug dans les 3 heures qui suivent, t'es content d'avoir une javadoc (même minimale) pour t'y retrouver dans un code assez obscure.

C'est pour ça que je suis pour un code très structuré et optimisé, systématiquement commenté mais de manière succinte. Ca évite de rendre la lecture imbuvable, ça évite justement au développeur de ne pas commenter du tout ses développements. Et moins il y a de lignes de code, moins il y a de possibilités d'erreurs et surtout plus elles sont facilement trouvables.

[pseudocode]

« 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 », conclut Smith.

Que pensez-vous de la conclusion de Steve Smith ?

Je suis entièrement d'accord avec lui. A tel point que j'aurais pu l'écrire moi-même. D'ailleurs je l'ai écrit.

Pour moi, il y a deux grandes familles de commentaire:

- le commentaire "boite noire", pour expliquer à l'utilisateur du code comment il peut utiliser la classe/fonction. C'est généralement la raison d'être des commentaires auto-générés par les IDE modernes (arguments, valeurs de retour, exception, ...)

- le commentaire "boite blanche", pour expliquer au mainteneur du code pourquoi une implémentation ou une technique particulière a été choisie.

[ptah35]

Lorsque je code, j'applique deux principes :

1. Le code que j'écris, je l'écris d'abord et avant tout pour qu'il puisse être lu par des humains et non par des machines, car même en admettant que personne d'autre que moi ne voie jamais mon code, si je le relis deux mois après l'avoir écrit, je suis à peu de chose près dans la même situation que si je n'en étais pas l'auteur.

2. Si je peux dire quelque chose en code, alors je le dis en code et uniquement en code. Pour le reste il y a les commentaires.

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

[takodjou]

les commentaires nous permettent de comprendre facilement le code plus tard
.

[hbomb]

je suis un adepte des commentaires, mais uniquement pour générer de la doc.

j'évite de mettre des commentaires dans les méthodes que je fais les plus courtes possibles afin d'éviter d'avoir des méthodes de 50 lignes ou plus impossible à debugger.

d'ailleurs, j'essaie de faire passer le message avec mes autres collègues pour leur dire de commenter leurs classes/méthodes afin qu'on puisse avoir une doc solide et un code plus facilement maintenable. Petit à petit ça marche

et puis il n'y a pas que ça, les noms explicites de classe mais surtout de méthodes (comme certains l'ont dit les charge(), extract() et load() de l'auteur, arg! c'est la dernière chose à faire à mon avis!!) et des variables, tout ça aide pour le travail en équipe.

[dclink]

Que ce soit pour une revue dans x mois ou pour faire en sorte que des developpeurs reprennent la main plus tard, je mets autant que je peux des commentaires ... plus sur le "comment" que sur le "quoi" ... Donc les variables et noms de fonctions/methodes ne sont la que pour le "quoi". C'est tres pretentieux de croire qu'un code est forcement compréhensible sans aucune once de commentaire...

[chaplin]

Je suis entièrement d'accord avec lui. A tel point que j'aurais pu l'écrire moi-même. D'ailleurs je l'ai écrit.

Pour moi, il y a deux grandes familles de commentaire:

- le commentaire "boite noire", pour expliquer à l'utilisateur du code comment il peut utiliser la classe/fonction. C'est généralement la raison d'être des commentaires auto-générés par les IDE modernes (arguments, valeurs de retour, exception, ...)

- le commentaire "boite blanche", pour expliquer au mainteneur du code pourquoi une implémentation ou une technique particulière a été choisie.

J'ajouterais les règles de gestion, quand on est pas du métier, le plus dur est de comprendre le métier de l'autre. Sur les quelques mission que j'ai effectué, j'ai constaté à chaque fois que les gens ne connaissaient pas le métier en globalité, que le savoir était dispersé et qu'il fallait reconstituer les pièces du puzzle. On perd beaucoup de temps. Mais j'ai toujours apprécié les commentaires dans le code, même s'ils avaient 10 ans, au moins on a de l'information que les gens du métier ne nous fournissent pas.

[marc.collin]

plusieurs livre sur le clean coding spécifie qu'un code bien écrit n'a pas besoin de commentaire.

il ne faut pas oublier que les commentaires doivent aussi être maintenu... j'ai souvent vu des commentaires qui n'était pu d'actualité et qui faisait perdre du temps au lieu dans faire économiser.

je crois en effet qu'il peut être possible d'omettre un commentaire en utilisant de bon nom de variable, méthode et un bon découpage.

une possibilité est de faire relire le code à quelques personne et voir s'il arrive à le comprendre.

[bizulk]

Je plussoie ce qui est dit plus haut : un code bien lisible est clair sur ce qu'il fait, un commentaire peut expliquer pourquoi il le fait.