Discussion :

[Michael Guilloux]

En programmation, des variables bien nommées valent mieux qu’un bon commentaire
Qu’en pensez-vous ?

On a tendance à dire, dans les bonnes pratiques de la programmation, que les commentaires permettent de rendre un code clair et facile à comprendre pour les autres développeurs qui devront en hériter. Cela permettrait également au programmeur de se repérer lui-même facilement dans son code lors de la maintenance.

Si cette opinion est largement partagée et les commentaires sont utilisés par la grande majorité des programmeurs, il existe toutefois des personnes qui ont un regard tout autre vis-à-vis des commentaires.

Comme l’a défendu et démontré par un exemple sur le blog Simple programmer, un développeur a soutenu que les commentaires sont plutôt des choses à éviter. Il était au départ un grand adepte des commentaires avant de basculer radicalement à l’opposé suite à certaines découvertes. Après avoir lu les bouquins « Complete Code » de Steve McConnell et « Clean Code » de Robert C. Martin, il réalise que l’utilisation des commentaires est une pratique plus nuisible qu’utile.

Il découvre aussi qu’il utilisait des commentaires dans ses codes pour deux raisons. La première, c’est qu’il ne nommait pas les choses d’une manière suffisamment claire de sorte à rendre inutile les commentaires explicatifs. La deuxième est que les méthodes et fonctions, qu’il utilisait dans ses codes, étaient trop larges et donc avaient besoin d’explication supplémentaire.

« J'avais cru que je faisais un bon travail, et que j'étais un programmeur consciencieux en écrivant des commentaires pour expliquer mon code et le rendre plus facile à comprendre pour le prochain développeur ». A-t-il dit. « Mais, quand j’ai commencé à appliquer ce que j'ai appris dans le Complete Code, et commencé à écrire du code qui était souvent plus clair que les commentaires que j'écrivais avant, j'ai réalisé que je faisais une faveur plus grande à tous les développeurs qui hériteraient de mon code que d'écrire tout simplement des commentaires. Je rendrais mon code encore plus clair ». A-t-il ajouté.

Il réalise aussi que l’utilisation des commentaires traduit l’incapacité du développeur à pouvoir montrer explicitement son intention dans le code.

« Quand j'ai lu le livre de l'oncle Bob, Clean Code, ma position s'est encore renforcée. Non seulement l'oncle Bob dit que nous devrions éviter les commentaires, il a dit - et montré - comment faire des commentaires, le plus souvent, indique un échec pour exprimer l'intention dans le code ».

Pour lui, un code avec des variables bien nommées est plus clair et communicatif qu’un « bon » code fortement commenté.

Pour le démontrer, il a utilisé un code réel à partir du framework .NET. Il s’est attaqué à une méthode à titre d’exemple qu’il a réécrite, en renommant les choses comme il se doit. Et le résultat, selon lui, est quelque chose de plus clair et plus propre.

Une autre raison pour laquelle il suggère encore d’éviter les commentaires, c’est que les codes sans commentaires sont plus faciles à maintenir.

Il a développé son point de vue dans un billet intitulé « Pourquoi les commentaires sont stupides, un exemple réel », sur le blog Simple Programmer.


Source : Simple Programmer

Et vous ?

Qu’en pensez-vous ?

Pourquoi devrait-on ou non ajouter des commentaires dans son code?

[dfiad77pro]

En C# et Java je privilégie la documentation des méthodes et attributs même private.

Le but à atteindre est que les méthodes se comprennent d'elle-même. Les commentaires sont présents lors de l'implémentation d'un algo complexe. Mon entreprise a un WIKI auquel on peut mettre un liens dans le code avec une explication schématisée claire.

Le nommage est pour moi un des aspect les plus difficile de la programmation, d'autant plus qu'en français sans accent , c'est moche ( norme de mon entreprise, et généralement en C# on ne met pas d'accent dans les variables même si c'est autorisé).


Des fois je relis des vieux code VB6 et je vois qu'il y a 1000 lignes de commentaires avant de débuter le code ( historique de modifs des dev), ça fait pas propre.

[micka132]

Je suis mitigé. Sur l'exemple qu'il donne autant à la lecture c'est plus concis, autant en cas de debug ça devient beaucoup plus embêtant puisqu'il faut faire beaucoup plus d'aller/retour entre toutes les méthodes qu'il créé.
Ensuite je ne suis pas forcement fan de multiplier des méthodes de quelques lignes qui ne servent que dans le contexte particulier d'une autre méthode. On arrive vite à des fichiers énormes et on perd rapidement en clarté globale.

Renommer les variables oui, remplacer tout par des méthodes bof, je ne parle même pas des nombreux cas où l'on doit ajouter un petit quelque chose qui fait que le nom que l'on a choisit n'est plus tout à fait juste...Et en cas d'oublie de refactoring du nom c'est bien pire qu'en cas d'oublie de modif de commentaire : soit on se fie au nom et c'est le drame, soit on "s'amuse" à naviguer vers chaque méthode pour vérifier qu'elle fait bien ce qu'elle dit.

[Jbx 2.0b]

Sujet plusieurs fois abordé, et je suis toujours pas d'accord. On se doit d'écrire son code avec des noms de méthodes/classes/variables le plus clair possible, et très souvent ça se suffit à soi même. Parfait. Mais il restera des cas ou les commentaires sont un passage obligatoire.

Je pense que son exemple de refactoring est un mauvais exemple. Il ne met en jeu que des connaissances propres aux développeurs lambda. Le vocabulaire est connu de tous : path, string, split, directory, separator, slash... Il suffit effectivement d'écrire correctement (grammaticalement parlant) son code pour qu'on saisisse l'algorithme. Très bien.

Maintenant on ajoute des connaissances métiers pointues (propre à un secteur d'activité en particulier) et on saupoudre d'un bon vieux algo basé sur une belle formule mathématique (choisie parmi d'autres pour une obscure raison). Ça ne marche plus. Il va falloir commenter (parfois abondamment) si on veut se faire comprendre de l'utilisateur du service, ou du type qui va venir le maintenir. Voir même lui donner un lien vers une doc.

[Aiekick]

Complètement en accord avec ça. ayant appris le dev en autodidacte et n'ayant jamais travaillé dans ce milieu on ne m'a jamais forcé à adopté cette démarche.

Et a chaque fois que je tombe sur du code blindé à la gorge de commentaire, de voir 20 lignes de commentaire pour une fonction qui en fait que 10, ça me rebute plus qu’autre chose et ai une envide fuir.

J'aime bien pouvoir balayer d'un traite la classe et ses méthodes. ( je n'ai jamais vraiment aimé l'explorateur de classe dans les IDE )

Je n'utilise les commentaires que quand la fonction n'est pas très claire, ou quand j'explique le fonctionnement d'un processus.

Par exemple chaque classe a un bloc de commentaire qui explique ce qu'elle fait et pourquoi elle existe, mais après je ne met pas plus d'une ligne, voir plus souvent rien, si les méthodes ou les var sont suffisamment explicite de par leur nom.

D'un autre coté je bosse tout seul sur mes programmes. Mais même quand je reprend un projet en stand-bye depuis plus d'un ans, je n’ai jamais vraiment galéré pour piger le pourquoi du comment de mes classes et méthodes.

Et au pire des test unitaire sont créé pour les classes et méthode qui ont un fonctionnement critique, et les tests aide à piger précisément le fonctionnement.

[MikeRowSoft]

Ce n'est pas incompatible avec les notions "d'héritage" du C++, ou même de savoir "l'importance" ou "pertinence" dans les programmes de chacune des instances qui les composes.
C'est très souvent les "schémas" des bases de données (les formes normales) qui introduisent se type de nommage via le langage SQL ou lors de l'apprentissage d'un langage de programmation.

[fredo38]

Le mieux est parfois l'ennemi du bien. De mes 20 années d'expérience en SSII dont une grande partie de programmation j'arrive à cette, ma, conclusion :
Pour les puristes du coding et des langages qu'ils maîtrisent, le naming des procédures, fonctions et variables se suffit à lui-même.
Pour les autres, dont moi, il faut passer par une phase de dé-tricotage du code (90% du temps) afin de comprendre ce qu'il fait, avant de pouvoir intervenir (très souvent pour corriger une erreur non prévue au départ).
Je passe rapidement sur le fait que les langages ne sont pas en français, ni qu'un terme en xxx n'est pas exactement le même en yyy.
L'avantage de commenter son code dès le départ et surtout au cours de sa vie permet d'être clair sur ce que l'on attend du traitement et sur les modifications que l'on y a apportées.
Alors oui pour des commentaires (concis) ET des variables, procédures, fonctions,... qui disent ce qu'elles f(s)ont et qui font ce qu'elles disent.

[Gulien]

Le sujet a été maintes fois débattu,
C'est évident qu'une variable se nommant "ActionEcheanceButoirDate" sera plus facile à lire que "Date1" pour quelqu'un qui lirait le code pour la première fois
Après reste à savoir l'ordre dans lequel on place les noms qui composent la variable
"ActionDateEcheanceButoir" ou "ActionEcheanceButoirDate" (Les trie-t-on par type de variable ou concept métier ?), mais ça c'est un détail de règle de programmation.

Pareil pour les méthodes.

Néanmoins, à force d'essayer d'atteindre la perfection on en oublie les bonnes pratiques qui sont de faire une documentation (JavaDoc ou autre) de ses méthodes...
Et encore plus si on découpe le code en une infinité de petites miettes à usage unique.
Je suis d'accord sur le principe, mais il faut que ça soit fait de façon extrêmement rigoureuse et documenté.

Comment le nouvel arrivant va savoir qu'il existe telle fonction à tel endroit si ce n’est pas répertorié / documenté ? Et dans ce cas, oui on peut se passer des commentaires.

Bref je me méfie des jusqu'au-boutistes du "pas de commentaires", et concernant les variables bien nommées, il y a toujours une limite à expliquer un concept en un mot...
au lieu de ce commentaire, j'aurais pu écrire "DaccordMaisDocumentons", beaucoup de gens auraient compris, mais est-ce que ça aurait eu la même signification?

[watchinofoye]

Qu’en pensez-vous ?

J'en pense que l'un n'empêche pas l'autre, voire qu'il vaut mieux adopter des noms explicites et clairs ET des commentaires clairs dans les cas où le code en lui-même a besoin d'explications sur son fonctionnement (de sorte à ne pas perdre de temps à se demander à quoi ça sert).

Concernant les noms, un truc que j'ai vu et qui m'a bien plu c'est l'habitude de nommer les types de données en fonction de l'unité. Par exemple (extrait des règles de codage de Médiane Système) :

Code :

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

1
2
3
4
5
6
7
8
9
10
dans un fichier.h regroupant les types :
typedef int pression_en_bar ; /* type entier- gamme 0 .. + 210 - unité : bar */
typedef int gain_mesure_pression; ; /* type entier- gamme 0 .. 10 - unité : sans */

dans un fichier regroupant des constantes :
const pression_en_bar offset = 2 ;
const gain_mesure_pression correction_gain = 10 ;

dans le fichier de la fonction :
consigne_pression = ( consigne - offset ) * ( pression_en_bar) correction_gain ;

À part ça, ça me fait toujours marrer de voir certains développeurs faire tout un pataquès, parfois plein de mauvaise foi, parce qu'ils trouvent que tel aspect de développement leur semble stupide et que tout le monde devrait faire comme eux alors qu'au final ce n'est que leur avis personnel.

[Arno_94]

Hello,

Je rejoins pas mal de mes camarades. Oui, bien nommer ses variables permet une meilleure relecture du code, tout comme ne pas utiliser systématiquement du sucre syntaxique. Ouais, c'est chouette de faire plein de choses en une seule ligne de code mais à la relecture et au debugage... En outre, ça n'apporte strictement rien à l'application finale.

Donc, oui pour bien nommer ses variables mais ça ne peut pas remplacer du commentaire, surtout du commentaire fonctionnel.

En relisant le code avec des variables bien nommées, on comprend mieux ce que le dév fait mais on ne comprend pas pourquoi il le fait...

[DarkHylian]

Pour moi, les commentaires doivent rester un complément utile au code.
Les noms explicites (d'une fonction,méthode,classe, variables, et autres entités) doivent permettre de comprendre rapidement ce à quoi sert ce qui est nommé. C'est la base de la base.

Sauf que voilà, il existe parfois un décalage entre les noms donnés et la compréhension que l'on peut en avoir à un moment donné.
Je prends comme exemple l'arrivée d'un nouveau développeur au sein d'une équipe habituée au code qu'elle maintient.

Premier point : il faut faire l'acquisition de la logique de l'équipe. Sans les commentaires ou une documentation efficace (mais synthétique), c'est une tâche ardue (j'en ai fait l'amer expérience).
Second point : non content de la logique de l'équipe, il faut un minimum de logique du métier visé par le code à maintenir.
Un logiciel spécialisé cible un métier (la ventes, le suivi de colis, la maintenance aéronautique, la génération de modèle 3D, etc.). Sans un minimum de bagage sur ce métier, le code est à la limite d'être de l'obscurantisme pur, voir une science occulte que l'on aimerait bien interdire à la manière de l'Inquisition.

Une fois ces premières barrières passées, les noms explicites deviennent clairs, et on peut faire des prouesses dans tout ça, mais ça prend un peu de temps (et beaucoup beaucoup plus sans aucun commentaire ni doc)

Et pour pouvoir se débarrasser de ces barrières, le commentaire est utile.
Si la documentation d'une entité commence à dépasser une 30aine de lignes ( en considérant une ligne par paramètres, une ligne pour la valeur de retour, et la description du fonctionnement), il faut se poser des questions sur l'entité elle-même. (N'est-elle pas sur utilisée ? Est-elle suffisante ou nécessite-elle une entité complémentaire ? N'y a-t-il pas un problème d'architecture autour ? )

Pour ma part, dans mes développements Java et Php, je me sers massivement de la JavaDoc et Doxygen (respectivement), pour tout ce qui est classe, méthode, fonctions, pour les variables membres uniquement quand c'est nécessaire (c'est rare).
D'une part parce que mon ami l'IDE m'affiche la doc en cours de route (ça me sert d'aide mémoire), d'autre part, parce que j'aime à penser que le dév qui passera après moi appréciera de pouvoir avoir une compréhension exhaustive de qui fait quoi sans devoir fouiller le code à tout bout de champs (chose qui me parait la plus horrible).

Pour les passages un peu plus compliqués, je prends le temps de commenter, surtout lorsque ça devient critique. Mais le bas blesse, qu'est-ce qui est critique dans un code ?
Quand je regarde le code que je produis, pour moi, rien n'est réellement critique : c'est du code structuré, qui fait ce qu'on attend de lui, simplifié autant que possible, en évitant des cascades de if/else imbriqués, des for (int i ... ) là ou on a des itérateurs, des tableaux, là où on peut utiliser des listes (plus efficacement).
Mais pour un autre dév qui arrive avec des yeux tous neufs sur le code, en ayant juste les compétences de dév, comment va-t-il l’appréhender ?

Le code parfait n'existant pas, et chacun ayant son approche, je pense qu'il est bon de compléter son code avec des commentaires pour bien insister sur la façon qu'on a eu de procéder, sans pour autant noyer le prochain dev dans un flot de commentaires qui lui ferait perdre le fil de sa lecture.

En résumé : la doc de code doit au maximum correspondre à 1/4 (j'ai une tolérance pour 1/3 lorsqu'il s'agit de fichier de classe) du code utile.
Et les commentaires devraient représenter entre 1/7 et 1/10 du code utile, dans le meilleurs des mondes. (je pense que 1 ligne de commentaire sur 10 lignes de texte devrait toujours être suffisant, au delà, il faut se poser des questions sur la complexité du code)

Mais là encore, ce n'est que mon opinion de développeur, et c'est la façon dont j'appréhende le code en tant que barbu (est-ce qu'il y a un rapport ? )

[Muska17]

Ca depend du contexte dans lequel on programme.

Si tu fais de la resolution numeriques d'equations en tout genre tu n'iras jamais mettre des noms de 20 caracteres a tes variables, tu mettras en general une seule lettre (ou un mot correspondant a la lettre grecque, bref vous m'avez compris), pour rester en coherence avec le contexte dans lequel tu programmes. Mais du coup tu as besoin de commenter pour t'y retrouver, car tu n'as pas forcement le temps de remettre le nez dans les bases theoriques a chaque fois.

Bref, encore un billet d'un blogueur qui a voulu faire le buzz avec un avis pseudo-iconoclaste, et qui n'a pas du faire grand chose a part du web ...

[martopioche]

C'est tout de même incroyable comment dans le monde du dev, les même débats reviennent régulièrement en négligeant ou ignorant tout ce qui aurai pu être dit ou écris. Dans ce cas, l'auteur démontre surtout une chose : il cite des références qu'il n'a clairement pas lu... Clean Code consacre un chapitre entier de 30 pages sur le commentaire du code et l'idée maîtresse est "il n'y a rien de plus profitable qu'un bon commentaire, il n'y a rien de plus néfaste qu'un mauvais commentaire". Si le chapitre précédent est consacré aux fonctions, il dégage en effet l'idée du bon nommage des fonctions. Et à aucun moment il ne dit qu'un bon nom de fonction rend le commentaire inutile !

Et la "démonstration" démontre justement qu'il n'a rien compris. Avant de se poser la question du renommage du paramètre pour faire sauter le premier commentaire, il aurai dût être question simplement de la pertinence de ce premier commentaire. En fait, cette remarque est vrai pour tout l'exemple. Les commentaires qu'il fait sauter servent à exprimer une intention, quel intérêt à les transformer en fonction ? Le code en lui même est-il réellement moins lisible sans ces commentaires ?

[martopioche]

Des fois je relis des vieux code VB6 et je vois qu'il y a 1000 lignes de commentaires avant de débuter le code ( historique de modifs des dev), ça fait pas propre.

Ah ce code legacy datant d'avant les gestionnaires de versions...

[NSKis]

Il faut les 2!!!

Quand vous avez du code qui voit passer plusieurs générations de développeurs, le nommage "futé" des variables n'est pas suffisant!!!

Le nom d'une variable aussi claire soit-elle n'indiquera jamais l'idée ou l'approche choisie par le précédent développeur pour implémenter une fonctionnalité

[Mouke]

J'ai toujours considéré un code parfait comme un code tellement bien construit qu'il ne nécessite aucun commentaire. Pour ça, le nommage des variables, des classes et des méthodes, l'organisation du code (répartir sur 3lignes ou tout condenser en une) sont autant d'éléments entrant en jeu.

Je code en gardant cet idéal en tête. Mais comme c'est une utopie, je continue à commenter.

[Excellion]

Que je sache l'un n'empêche pas l'autre.

C'est d'ailleurs souvent l'argument premier des débutants : ils ne documentent pas leur code, le nom de variables suffit.
6 mois après, quand on reprend les 1500 lignes que représentent l'unique méthode d'une classe, on pleure un peu. Beaucoup, même.
Surtout que les dénominations qui semblaient claires pour la personne à une époque le sont nettement moins pour une autre personne, quelques temps après.

Bien documenter son code (notamment les classes et les méthodes) permet de savoir d'un coup d'oeil ce que fait le code.
Bien nommer les choses permet de savoir à quoi elles servent, dans le détail.

En somme les deux sont importants, mais ça, il n'y a que l'expérience qui peut le démontrer...

[dfiad77pro]

Ah ce code legacy datant d'avant les gestionnaires de versions...

Le pire c'est que lorsque ce code est passé en SVN (2004 je crois) , les devs suivant ont continués à commenter

Résultat on a une appli de 100 000 lignes de code qui à mal vieilli, qui coute cher en maintenance et qui pourrai tenir en 20 000 lignes en .NET ou JAVA

[minirop]

je trouve l'exemple qu'il a utilisé mal choisi (voire mal foutu), il a juste remplacé les commentaires par un appel de fonction. Je vois vraiment pas l'intérêt de faire ça (pour ce code précis).

[Luckyluke34]

Pour moi, le doute induit par la présence de commentaires potentiellement obsolètes dépasse la plupart du temps leur bénéfice. Et je ne parle pas des commentaires "migrateurs" qui sont déplacés au fil du temps, parfois jusqu'à être séparés de leur ligne de code d'origine...

Donc très peu de commentaires, sauf pour expliquer du code obscur par nature (workaround plus ou moins sale, algo complexe). La documentation se trouve plutôt dans le nom des variables/méthodes ou dans les tests.