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

Le , par Michael Guilloux, Chroniqueur Actualités
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?


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


 Poster une réponse

Avatar de dfiad77pro dfiad77pro - Membre éprouvé https://www.developpez.com
le 15/04/2015 à 11:00
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.
Avatar de micka132 micka132 - Membre expert https://www.developpez.com
le 15/04/2015 à 11:00
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.
Avatar de Jbx 2.0b Jbx 2.0b - Membre expérimenté https://www.developpez.com
le 15/04/2015 à 11:04
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.
Avatar de Aiekick Aiekick - Membre expérimenté https://www.developpez.com
le 15/04/2015 à 11:37
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.
Avatar de MikeRowSoft MikeRowSoft - Provisoirement toléré https://www.developpez.com
le 15/04/2015 à 11:43
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.
Avatar de fredo38 fredo38 - Membre régulier https://www.developpez.com
le 15/04/2015 à 11:43
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.
Avatar de Gulien Gulien - Membre régulier https://www.developpez.com
le 15/04/2015 à 11:49
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?
Avatar de watchinofoye watchinofoye - Membre régulier https://www.developpez.com
le 15/04/2015 à 11:50
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
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.
Avatar de Arno_94 Arno_94 - Membre actif https://www.developpez.com
le 15/04/2015 à 12:02
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...
Avatar de DarkHylian DarkHylian - Membre habitué https://www.developpez.com
le 15/04/2015 à 12:24
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 ? )
Contacter le responsable de la rubrique Accueil