Temps de lecture 8 min
En programmation, 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, nous dit Wikipédia.
De fait ils sont le plus souvent utilisés pour expliquer le code, et contrairement à ce dernier qui nécessite un langage de programmation, les commentaires se font dans une langue humaine, généralement en anglais.
C’est une opération indispensable et une partie intégrante du travail du développeur, afin qu’un autre puisse comprendre et éventuellement modifier le code initial (quitte à ce que cet autre soit l’auteur même des commentaires, reprenant son code quelques temps plus tard).
De par le fait que sa nature en autorise l’accès et le ré-appropriation, on comprendra que ces commentaires soient encore plus importants dans le cas d’un logiciel libre.
Il se trouve cependant que, par paresse, manque de temps ou mépris pour ce qui ne serait pas de la programmation stricto sensu, ils sont parfois quelque peu négligés par les développeurs.
Or l’hypothèse défendue ici est qu’il y aurait une corrélation directe en la qualité des commentaires et la qualité du code.
Affirmer ainsi péremptoirement que l’un n’irait pas sans l’autre est somme toute assez osé. Mais cela a le mérite d’évoquer cette « face cachée » de la programmation qui fait aussi partie des compétences attendues d’un bon développeur[1].
Si les commentaires sont moches, le code est moche
If the comments are ugly, the code is ugly
Esther Schindler – 15 novembre 2009 – IT World
(Traduction Framalang : Goofy)
C’est un peu dur, je sais, mais finalement je crois que c’est vrai.
Le développeur de Plone Martin Aspeli m’a signalé un billet assez judicieux dans lequel un programmeur en C faisait part de trois règles apprises à ses dépens. Celle qui a particulièrement attiré l’attention de Martin (et la mienne) est la suivante :
Les bons programmes ne comportent aucune faute d’orthographe ni de faute de grammaire. Je pense que cela vient probablement d’une attention soutenue aux moindres détails ; dans les programmes excellents tout est correct à tous les niveaux, jusqu’aux points qui terminent les phrases de commentaires.
« Allez, tu charries ou quoi ? ». Vous pourriez croire que pinailler à ce point est indigne de vous, « Et bien je m’en vais commencer à vous signaler les erreurs dans votre code lui-même ». J’ai été bien embarrassé les deux ou trois fois où ça m’est arrivé.
La programmation, que vous la pratiquiez en enthousiaste de l’open source ou parce que vous êtes au service du patron, est un exercice qui exige de l’attention aux détails. Quiconque écrit un logiciel doit être pointilleux, sinon le code ne fonctionnera pas. Je suis sûre que je n’ai pas besoin de vous citer la série des célèbres bogues de programmation dont s’est rendu coupable un programmeur qui a utilisé une virgule et non un point, ou des plantages aléatoires provoqués par deux lignes de code placées au mauvais endroit ?
Il est possible que mon jugement soit faussé par mes fonctions d’écrivain et d’éditrice, mais je crois fermement que si vous ne pouvez pas trouver le temps d’apprendre les règles de syntaxe de la langue (y compris la différence entre « c’est » et « ces », ou encore « m’a » et « ma »), je ne crois pas que vous puissiez être beaucoup plus consciencieux pour écrire du code en respectant les bonnes pratiques. Si vos commentaires sont négligés, je m’attends à trouver du code négligé.
Mon postulat vient de ce que m’a enseigné un éditeur très brillant, il y a dix ans (Laton McCartney, si tu lis ça : merci !). Si tu peux écrire le chapeau, disait-il, tu peux écrire l’article très facilement. Si tu ne peux pas écrire le chapeau, c’est que tu ne comprends pas encore ce que tu veux dire, et tu ne devrais pas commencer à écrire (le « chapeau » est le petit paragraphe d’accroche qui suit le grand titre, qui dit en un mot de quoi il est question et invite gentiment le lecteur à en savoir plus). De filandreuses « explications » du code dans les commentaires de l’application (c’est-à dire, ceux qui se lisent comme de bonnes excuses) indiquent que le développeur ne savait probablement pas ce qu’il faisait au juste. Ce qui signifie que son code est éligible au titre de nid à bugs.
Se plaindre de la mauvaise documentation interne est un vieux refrain, mais il existe une raison pour laquelle il est important de la faire bien. Vos commentaires sont la seule façon dont vous disposez pour communiquer avec la prochaine personne qui regardera votre logiciel (il se peut même que ce soit vous) en profondeur, et pas juste une ligne ou deux. À quoi pensiez-vous en écrivant ce code ? D’accord, du code « auto-documenté » c’est l’idéal, mais c’est un peu arrogant de prétendre que vous l’avez atteint, et ça l’est tout autant de ma part si je prétends que mes phrases n’ont pas besoin d’être révisées (elles en ont besoin, je suis bien contente d’avoir un correcteur).
Un autre problème habituel dans la médiocrité des commentaires apparaît lorsque les développeurs mettent à jour le code sans mettre à jour les commentaires ; comme l’a expliqué un consultant, les commentaires ne sont pas testés. Mais est-ce qu’il ne s’agit pas là encore d’un manque d’attention aux détails ? À chaque fois que vous n’êtes pas totalement attentif, vous êtes prédisposé à laisser tomber un petit bout de logique.
Vous voulez quelques exemples ?
En voici un tiré d’une explication à propos d’un choix de conception. (« oui, je devine que c’était probablement intentionnel », a écrit le programmeur qui m’a montré cet exemple. « mais c’est bien là le problème : il faut que je devine ».)
« ... des questions prévues pour injustifier un débat... »
Voici maintenant une authentique ligne de code avec un commentaire. Notez que le commentaire met l’accent sur la faute d’orthographe. Sans compter que le commentaire vous indique que le programmeur n’avait pas la moindre idée de ce qu’il faisait au départ. Particulièrement parce qu’il n’aurait pas dû écrire « finished » (NdT : fini) dans ce bout de code, mais qu’il aurait dû essayer « complete » (NdT : terminé).
if item.getState() == 'finsihed' : #est-ce correct ?
Bon, je vous accorde quelques exceptions. Si l’anglais n’est pas votre langue maternelle, il est possible que les commentaires que vous laissez dans votre code montrent que vous n’êtes pas à l’aise pour écrire en anglais. Cependant, en ce qui me concerne je n’ai pas trouvé que c’était le cas. Comme beaucoup d’Américains s’en sont rendu compte, les capacités en anglais des « étrangers » sont généralement bien meilleures que les nôtres. Parmi les développeurs que je connais, ceux qui ont des lacunes dans leur maîtrise de la langue anglaise en sont conscients et font tout leur possible pour qu’un anglophone passe en revue leur documentation.
Je ne me lancerai pas dans des considérations sur l’indentation du code et des commentaires, c’est une guerre de religions. Mais j’ai rencontré des développeurs qui réagissaient aussi violemment devant un formatage de code « moche » que moi devant une grammaire moche.
Les environnements de développement modernes procurent la discutable possibilité aux développeurs d’être négligents sans effets pervers ; une interface glisser-déposer vous permet de créer une application vite fait bien fait (ou plutôt mal fait, j’en ai peur) avec bien moins d’horribles dommages collatéraux qu’à l’époque où les logiciels étaient généralement écrits en assembleur. Pourtant, d’une certaine façon, j’ai du mal à considérer le « je peux être négligent » comme un avantage réel.
La règle du commentaire « moche » vaut autant pour les applications propriétaires que pour les logiciels open source. Mais les développeurs de FOSS (NdT : Free and Open Source Software, les logiciels libres et open source) doivent faire beaucoup plus attention encore pour deux raisons. La première, c’est qu’au bureau, vous avez de grandes chances de croiser le développeur du code mal fichu et de pouvoir lui poser des questions (ou de lui en coller une, si c’était vraiment horrible). De plus, dans la communauté open source, davantage de gens regardent dans le code et ont besoin de le comprendre.
Toutefois, lorsque j’ai suggéré à des développeurs que « si les commentaires sont moches, le code est moche », beaucoup n’étaient pas d’accord. Et vous non plus peut-être. J’aimerais savoir pourquoi, et je vous invite donc à laisser un… commentaire.
1138
Plutôt d’accord.
Quand j’ai commencé mon boulot actuel, j’ai dû faire un site web dans le cadre d’un partenariat. Je l’ai fait en Spip et, quand une représentante du partenaire était là pour bosser avec moi, elle était étonnée que je lui dise que je prenais la peine que le code soit clair au cas où quelqu’un devait reprendre le truc.
En fait, elle croyait que je faisais ça parce que je voulais déjà quitter mon boulot.
Il est vrai que je fais peu de commentaires. Les commentaires que je mets sont surtout des repères visuels pour différentes portions du code (<entoutpetit>J’ai un peu honte de parler de code pour les squelettes Spip que je fais mais, techniquement, c’en est…</entoutpetit>).
Mais faire un code clair est pour moi une manière de pérenniser la chose. Non, je ne veux pas quitter ce boulot, à peine engagé ; non, je n’ai pas peur d’être viré ; etc… C’est juste qu’il faut aussi penser à l’avenir. Je, tu, il n’est pas éternel. Et c’est quand même plus cool, pour une personne qui doit reprendre un projet au pied-levé, d’avoir des indications que de devoir tout déduire (ce que j’ai déjà vécu).
Je pourrais, oui, détailler les quelques boucles complexes que je fais. Et cet article va m’inciter à le faire plus (surtout que je commence à bosser sur un site international). Mais, à la limite, un code écrit proprement n’a pas besoin de commentaires (hormis les repères). Sa structure se suffit à elle même, sauf pour expliciter une fonction plus complexe.
Par contre, les commentaires peuvent aussi servir d’aide-mémoire pour quand on rédige le mode d’emploi… 😉
antistress
Les commentaires peuvent aussi servir de tribune pour insulter ses pairs 😉
http://www.strapontins.org/2008/04/…
https://bugs.launchpad.net/ubuntu/+…
seza
Une autre religion veut, à la manière des développements dirigés par les tests, que l’on écrive dans un premier temps les commentaires puis dans un second temps le code.
C’est très utile lorsque l’on s’apprête à développer une longue série de code de quelques centaines ou milliers de lignes. Ça aide à garder ses repères et à ne pas perdre de vue son objectif final.
makidoko
Ce qui se conçoit bien s’énonce clairement et les mots pour le dire arrivent aisément.
Comme Seza le précise, je suis pour cette religion qui consiste à raconter l’histoire du programme avant de s’attaquer à son algorithmie.
Mais quitte à commenter son programme, autant lui donner des noms de variables et de fonctions parlants et les déclarer dans les bons espaces. Mais, il y a fort à parier, que celui qui prend ce soin de commenter clairement son code, use du même soin à veiller à la lisibilité de ce dernier.
lawl
Quel interet de publier cela sur planet-libre !?
Aucun,…..
cham
C’est une bonne chose, de communiquer sur cette arrière boutique des logiciels. Comme le législatif, le marketing, le commentaire ou l’archi sont des composantes très importantes. Et faire/traduire des articles grand public sur le sujet ne peut être que bon.
dzada
Hello
Pour répondre à Iawl, Non, je juge qu’il est tout à fait logique de le publier sur Planet-Libre car c’est Le partage d’information de conception (et pas seulement de code) qui fait le libre.
Sinon, je comprend qu’il y ai parfois peu de commentaires, car parfois le code est limpide (même pour moi si je ne l’ai pas écrit, ou même en débarquant dans un projet)
Cependant, j’ai bien dit "parfois" i.e. la plupart du temps ce n’est pas le cas. Comme solution assez facile à imposer en projet, j’ai essayé plusieurs fois Doxygen. On dit au développeur de mettre un "brief" (brève description) de chaque classe, fonction qui dépasse l’accesseur, ou le Setteur de base (de base i.e. il n’y a aucun traitement sur les données, aucun test)
Et ensuite documenter "toutes les fois au minimum où ils se sont posé une question"
=>Ca marche pas mal car un codeur qui ne commente pas est donc un codeur qui ne pensent pas, et heureusement, c’est rare. Ensuite l’intéret de Doxygen la dedans était d’avoir tout celà mis en forme est accessible sur un support propre (html, pdf…).
Cependant, le meilleur moteur à ca, c’est de montrer l’exemple, normalement, un codeur un tant soit peu correct ayant profité des commentaires présents dans le code finit naturellement par rendre l’appareil en faisant des commentaires.
Bye
Desidia
@lawl
Au moins, ça m’a fait rire!
Il y a de nombreux articles sur la manière correcte de commenter son code, et la polémique semble inépuisable. Je me rappelle avoir lu que l’excès de commentaires était aussi criticable ("n’insultez pas l’intelligence de vos successeurs") et que souvent, indiquer une brêve référence à la documentation du langage était préférable.
djib
Personnellement je suis partisan des codes sans commentaire. Ma vision d’un code « beau » est un code parfaitement limpide, découpé en petit fragments dont la logique est visible au premier coup d’œil. Avec des noms de fonctions bien choisies qui ne dépassent pas disons une vingtaine de lignes et des noms de variables idoines, les commentaires ne font qu’alourdir ce dernier, voire guider quelqu’un sur une mauvaise piste si ils ne sont pas à jour.
Au passage, si vous voulez améliorer la lisibilité d’un code, n’hésitez pas à passer par http://refactormycode.com/, une communauté très active qui vous aidera à rendre votre code plus compréhensible et synthétique.
Je suis d’accord que dans certains cas — complexes ou liés à des contraintes métier par exemple — le commentaire de code peut-être essentiel, mais je préfère alors le lire dans les tests que dans la réalisation, car le commentaire a une valeur pas si éloignée de celle d’une spécification : « les 4 lignes suivantes *devraient* faire ça ».
Après je pense que l’article doit avoir raison sur le fait que la programmation comme l’orthographe demandent une attention particulière et sont en ce sens liés.
Régis
Entièrement d’accord avec djib.
Une référence supplémentaire sur le sujet : le livre "Clean Code: A Handbook of Agile Software Craftsmanship" de Robert C. Martin.
lawl
"Pour répondre à Iawl, Non, je juge qu’il est tout à fait logique de le publier sur Planet-Libre car c’est Le partage d’information de conception (et pas seulement de code) qui fait le libre"
Franchement autant l’article me plait autant cela n’a aucun rapport avec le libre cela s’applique aussi pour n’importe quel logiciel propriétaire…On pourrait alors tout aussi bien lire des article qui nous apprennent à programmer….
Baptiste
En fac d’informatique, on avait une prof qui voulait qu’on écrive nos commentaires… Elle nous demandait même d’écrire les commentaires AVANT le code, on a toujours trouvé ça débile et chiant, mais c’est vrai qu’une fois qu’on avait écrit le commentaire, écrire le code devenait beaucoup plus simple.
Emmanuel
La vrai qualité est d’écrire quelque chose de compréhensible… sans commentaire. Si un commentaire est necessaire, c’est le signe que le code n’est pas proprement découpé et donc le signe d’un programmeur qui manque de rigueur. Mon opinion de developeur open source en tous cas
zaz
Les commentaires sont utiles. Mais bon, franchement, durant mon expérience professionnelle j’ai toujours été trop à la bourre pour en écrire souvent… J’aimerais savoir si ce que je dis est fréquent : J’ai essentiellement travaillé pour des traders de toutes sortes, banques, cartes de crédit… Putain, fallait faire vite parce qu’une loi changeait, ou qu’un nouveau produit devait être là du genre la semaine prochaine (ah bon, c’est con de ne pas l’avoir dit plus tôt), ou un truc qui n’était disponible que dans la journée de travail devenait 24 H sur 24 (arrangez vous pour le batch). Tout de suite, sinon on va perdre du fric. Les commentaires, j’ai pas souvent eu le temps d’en écrire… Je me suis généralement limité aux cas où je faisais un truc douteux (par manque de temps), ou une ruse tellement rusée qu’une semaine après avoir écrit le code, j’aurais eu du mal à la comprendre… Travailler dans l’urgence, quoi. Je parle au passé car je suis maintenant semi-retraité. Sans être riche, j’ai gagné assez de fric pour ne plus avoir vraiment besoin de travailler (merci American Express) : Je ne code plus que pour le plaisir, et là, des commentaires, j’en mets beaucoup… Des fois, des trucs qui n’ont pas grand chose à voir avec le code, juste histoire de rigoler un peu 😀
yoko
Je suis tout à fait d’accord que les commentaires sont extrêmement important. Mais il faut pas non plus allez chercher les détails de chaque conjugaison, orthographe et typographie dans les commentaires. D’une part les commentaires en anglais, ça laisse, beaucoup de personnes dans les chou que ce soit dans l’écriture ou dans la lecture. Un jeune russe, un français ou un chinois qui fait des fautes dans une phrase en anglais, pour moi ça ne remet pas en question sa qualité de programmeur.
J’ajouterais que si les anglophone ne connaissent pas beaucoup ce genre de problèmes, la dysorthographie est une vraie maladie et je ne vois pas en quoi quelqu’un qui serait touché par cette maladie ne serais pas un bon programmeur.
Ensuite le nom des variables par exemple c’est autre chose, c’est suffisamment simple et il y a assez de liberté pour ne pas se tromper.
Enfin je ferais remarquer que l’un des contributeur les plus connu (puisqu’il n’est autre que le bras droit de Linus Torvald), Alan Cox, affirme qu’un bon programme n’a pas besoin des commentaires, puisque ça lecture est tellement fluide et propre pour qu’il se comprenne sans. Je trouve que c’est un point de vu qui se défend.
Je trouve qu’avoir des idées aussi arrêté c’est la pire chose qui puisse arriver au libre. Vous souhaitez être élitiste ? Un programmeur qui se respecte doit maitriser l’anglais, les mathématiques, la physique et l’électronique sur le bout des doigts ? Je ne crois pas que c’est en se montrant aussi élitiste que l’on fait avancer le libre. Partout on dit qu’il y a un manque de contributeur, si en plus on leur fait peur en leur disant qu’ils ne sont pas assez bon. On ne va plus s’en sortir.
ney
Je suis toujours surpris que le L.L. fonctionne (souvent bien !) alors que la doc se résume aux sources et leurs commentaires. Je ne sais pas comment font les communautés pour maintenir et faire vivre leurs développements parfois longtemps de cette façon. Je fais du soft (propriétaire) dans l’aéronautique et là, croyez moi, on écrit des milliers de pages de spécifications, de dossiers de conception, de plans de tests sans lesquels on ne saurait plus rien faire, sans compter des rapports d’inspection pour justifier qu’il n’y a pas d’anomalie dans les autres documents, puis des revues de ces rapports. Tous cela nous parait, sinon naturel, au moins utile (et exigé par les Autorités de certification). Certes, l’enjeu n’est pas forcément le même, mais de nombreux L.L. complexes évoluent pendant de nombreuses années et d’une façon qui ne semble pas porter préjudice à leur qualité, au contraire. Je n’ai jamais eu le loisir d’étudier les sources de LL comme OOo ou Linux, mais les commentaires doivent vraiment être aux petits ognons. Je suis admiratif.
Martin
J’ai un avis plus mitigé sur la question. Je pense que le code doit être suffisamment clair et ainsi ne pas être surchargé de commentaires, mais il ne faut pas non plus s’interdire d’en mettre. Ce qui est clair pour le développeur au moment ou il écrit son code ne le sera peut être plus pour un autre développeur ou même pour lui même à un autre moment.
En résumé, il faut écrire du beau code ET des commentaires pertinents. l’un ne remplace pas l’autre, ils se complètent !
bagou
Un bon critère d’évaluation pourrait être également:
"Approprie toi ce code sans commentaires pour savoir si tu es un bon développeur."
small
J’ai toujours considéré que les commentaires sont indispensables. Ils sont le mode d’emploi que l’on est bien content de pouvoir consulter quand on découvre ou tout simplement quand on redécouvre.
Mais soyons réalistes, si mes commentaires sont rédigés en respectant les règles de grammaire, d’orthographe et de syntaxe, je ne fais pas pour autant de la poésie et peu m’importe de mettre des majuscules au début d’une phrase et un point à sa fin. Je vais me contenter d’aérer mes commentaires pour qu’ils soient lisibles aisément. C’est de l’informatique, ce n’est pas un essai.
La langue utilisée pour mes commentaires est le français, bien entendu.
J’… ceux qui usent de l’anglais, sans que ce soit indispensable.
Il s’agit là d’une forme de snobisme.
Je fais un effort uniquement si mes commentaires sont destinés à être exploités par des personnels non francophones.
Au final :
– la beauté des commentaires est bien moins importante que l’efficacité du code,
– au regard de l’évolution de l’enseignement, je doute fortement que les informaticiens soient tous des as de la rédaction des commentaires.
remi
Cela fait pas loin de 20 ans que je programme, et j’avoue les commentaires sont pour moi essentielles, pas uniquement pour une autre personne, simplement pour moi, j’écris énormément de code dans une année et cela dans plusieurs langages simultanément. Bien souvent je dois intervenir dans des portions de codes que j’ai écrites il y a plusieurs mois, si je n’avais pas les commentaires pour m’aider je devrai redécoder ce que j’ai écrit, donc une perte de temps.
Les commentaires représentes qu’une partie de la qualité d’un code source, j’ajouterai des programmes de tests (automatique si possible), un bon découpage objet (une bonne conception donc), simplicité du code, sécurité du code (éviter aussi les attrapes nilgaut, en C/C++ cela ne manque pas), propreté des listings (indentation propre, entêtes de fonctions, de fichiers), la non redondance de code, et j’en oublie. Je me fixe ces règle là, étrangement mon code est robuste et facilement récupérable, malheureusement le code que je récupère d’autrui ne respecte bien souvent aucune de ces règles. J’ajouterai que certain on comme argument le manque de temps, je pense que c’est un faux problème, combien coute un programme mal écris, à mon avis énormément plus chère qu’un programme bien écris, mais c’est tellement plus facile de ne pas être rigoureux… Au passage l’ajout d’un commentaire au dessus d’une ligne de code ne prend que quelques secondes, à moins d’être un handicapé du clavier.
dada
Sans vouloir faire trop de promo, je voudrais vous dire qu’a Epitech, on nous apprend a pondre du code clair. Pas plus de 26 lignes par fonction, pas trop de fonctions par fichier, toujours ajouter des espaces et de retours à la ligne pour aérer le code… De cette façon, même s’il n’y a pas de commentaires, le code est assez lisible…
viking
Mes commentaires me servent de pense bète pour la prochaine fois que vais travailler sur un bout de code.
Autrement dit, chez moi un commentaire ne reste pas plus de 3/4 jour dans un programme 😉
Margot
Il est vrai que les commentaires restent important, je viens d’en faire les frais en mettant la main dans les premières ligne de codes que j’avais fait y a de ca quelques années, et je m’apercoie que les commentaires qui ne sont pas là justement me font bien defaut pour comprendre mon style de codage de l’époque. Alors au final on s’en sort mais avec une perte de temps qu’aurait pu être évité.
Maxence
@1138 belle philosophie ! Si au moins tout le monde était comme toi, je me récupérerais pas du code de porcins à analyser pendant des heures pour tenter de comprendre la logique du ou des premiers arrivés sur le projet…
Xav
Au delà du principe de réalité qui oblige à tenir compte du niveau de rédaction très disparate chez les développeurs, je retiens comme l’auteur le soucis du détail.
Dans la plupart des cas, les manques sur l’écriture des commentaires ne sont que le symptôme le plus visible du problème, qui peut être soit un problème de rigueur, soit le mépris de la vie du code sur le long terme (couches, surcouches, autres intervenants, débutants – autant d’autres réalités à prendre en compte).