Littérature de code
J’aime bien lire les commentaires de code. Il y a une vraie littérature dans ces lignes écrites en langage naturel, dispersées au milieu des lignes de codes.
Bien sûr il n’y a pas que des chefs d’oeuvre, et même souvent il n’y a rien. Et rares sont les programmes que j’ai vu qui exploitent pleinement la force et l’importance des commentaires.
On a tort de penser que l’on écrit du code pour la machine. Je pense qu’on écrit du code pour qu’il soit lu par un tiers. Le cas échéant, ce tiers peut-être l’auteur lui-même.
En pensant que l’on écrit du code uniquement pour qu’il soit interprété par la machine, on oublie les points suivants :
- les langages avec lesquels nous programmons sont des langages bien particuliers car ils ne sont pas « parlés ». Ce ne sont que des langages écrits, sans réels pendant du côté de la pratique orale.
- ils doivent faire plus qu’un langage écrit, et pour cela il faut y introduire l’écriture d’une langue parlée : les commentaires.
- un code qui n’a pas de commentaire n’a donc pas de voix. Il devient potentiellement inaudible.
- un code sans commentaires n’a pas d’avenir, pas d’évolution possible : il peut bien faire ce qu’il fait, mais n’évoluera pas, ou peu. C’est comme s’il n’était pas remis dans le circuit, en circulation, pour pouvoir être modifié et réutilisé, ne serait-ce qu’à des fins pédagogiques.
Il faut dire que les mécanismes de commentaires par défaut sont très monotones.
Généralement un caractère spécial pour indiquer que c’est un commentaire qui va suivre, et c’est tout.
Je vois pourtant un intérêt à distinguer certaines formes de commentaires. Par exemple, avoir la possibilité de commenter sur trois niveaux :
- Le niveau factuel : le commentaire dit en langage naturel ce qui va être opéré et le décrit. C’est la niveau le plus utilitaire et dont les bénéfices pour la lecture du code sont immédiats.
- Le niveau contextuel : le commentaire décrit le contexte qui justifie les choix que l’auteur a fait, ou les chemins qu’il a emprunté. Il fait part des erreurs qu’il avait commises avant d’arriver à la solution définitive.
- Le niveau humeur : c’est un niveau important du commentaire qui permet à l’auteur d’exprimer sa personnalité, de rendre compte de l’unicité et de la singularité de son travail. C’est une activité importante qui favorise la mise en mémoire du code et qui donne « de la couleur à l’architecture logicielle », et cela aussi bien pour un tiers que pour l’auteur lui-même.
Dans la programmation aussi on peut décider de travailler soit sur le long terme soit sur le très court terme.
Google code search nous permet de faire des recherche « marrantes » sur ces fameux commentaires 🙂
Exemples :
http://www.google.com/codesearch?hl=en&lr=&q=%22%C3%A7a+marche+pas%22&btnG=Search
http://www.google.com/codesearch?hl=en&lr=&q=%22on+s%27en+moque%22&btnG=Search
Voir :
http://valleywag.com/tech/google/lets-abuse-googles-new-source-code-search-205499.php
ou
http://www.kuro5hin.org/story/2004/2/15/71552/7795
[Reply]
D’une manière générale, je réduis les commentaires au minimum car ils constituent une forme de duplication d’avec le code écrit juste à coté. Et l’on sais pour l’avoir vue très souvent que quand le code devient plus gros, cette duplication dérive beaucoup (quand j’arrive sur un projet, je commence par enlever les commentaires faux et il n’en reste souvent plus beaucoup après).
Les commentaires sont parfois utilisés pour aider à la compréhension du code. Cette pratique est pour moi hérité de l’enseignement. En effet, dans les livres et les cours de programmation, les commentaires sont très pratiques pour expliquer justement le code. Mais dans un code professionnel, les développeurs sont sensé connaitre un minimum. Ils peuvent apprendre évidement, mais cela ne justifie pas pour moi l’usage des commentaires. D’une manière général, je préfère essayer d’écrire du code directement lisible. Demander au développeur d’écrire des commentaires, c’est faire passer le message « le code n’est pas lisible par un humain, ajoutez des explications » alors que le message devrait être « faites du code lisible ». Comme vous le dites, on a tord de penser que le code est écrit pour une machine. Pour ce qui est d’introduire un langage parlé, je comprend l’argument, mais je ressent ce discours parlé comme du bruit. Les langages structurés sont un relativement (ça dépend des langage) bon moyen d’exprimer les concepts et abstraction que l’on essaie de capturer.
Par ailleurs, les commentaires sont parfois utilisés pour faire de la qualité au sens : « je dis ce que je veux faire et je fais ce que j’ai dit que je voulais faire ». Mais cela est avantageusement remplacé par les tests unitaires. Ce type de commentaires peut être remplacé dans une premier temps par des assertions exécutables. Dans un deuxième temps, on se rend compte qu’il est plus pratique de déplacer ces assertions à l’extérieur de l’application, dans une application dédié aux tests.
Remarque à propos du niveau contextuel:
La présence du message contextuel dans le code est une nuisance pour la recherche des erreurs. En effet, en lisant le commentaire, le lecteur se place dans le même état d’esprit que le celui qui a écrit ce code. Du coup, il ne voit pas l’erreur. C’est une remarque que j’ai lu dans « The Psychology of Computer Programming » par Gerald Weinberg. Il ne faut pas minimiser ce phénomène. Tout d’abord, dans les milieux professionnels, le code est essentiellement lu lors de la recherche d’erreur. Mais même si le code est beaucoup lu par des pairs pour d’autres raisons, comme c’est le cas lors qu’on programme en binôme ou que l’on pratique la propriété collective du code, il serait dommage de se priver de cette opportunité de détecter des erreurs.
Bref, à cause de toutes ces remarques, les commentaires est une pratique qui nuit à la qualité du code.
[Reply]
Oui, effectivement, j’aborde le problème du point de vue professionnel. Je m’intéresse évidement aussi beaucoup à l’open source, mais il est vrai que je suis parfois très déçu par le niveau de qualité de certain logiciel pourtant très prometteur sur le papier. Enfin, c’est ça aussi l’open source, une variété infinie.
Bref, je voulais juste rajouter un petit message car décidément, cette vision des commentaires me fait réfléchir…
C’est surtout cette idée de langage parlé qui m’a plus. Je ne suis pas tout a fait d’accord avec cette idée que le langage de programmation à besoin d’être parlé ou d’avoir un support parlé. Cela serait un peut trop bruyant dans ma tête si s’était le cas :-). Après un certain niveau de pratique, le langage de programmation utilisé devient une compétence inconsciente. De la même manière qu’on conduit une voiture sans réfléchir au levier de vitesse ou à l’accélérateur. Vous n’êtes pas en permanence à vous demander si le frein est en deuxième ou troisième position. Utiliser un langage parlé en plus, c’est comme si on avait besoins de traduire mentalement tout ce qu’on dit en français quand on parle anglais.
Ceci dit, je comprends justement l’argument puisque effectivement quand on début en anglais on pratique souvent cette traduction mentale. Mais il peut être intéressant pour l’amateur d’évoluer vers plus d' »aisance ».
Enfin, pour répondre à ton message Christian. J’ai l’impression que tu décris ici des programmes « oeuvre d’art » qui auraient un état figé et dont on pourrait en étudier l’histoire, la genèse… Pourquoi pas. J’aime bien aussi quand ça peut servir à quelque choses et s’est vrai qu’a titre personnel je vais plus rechercher dans du code des idées d’architectures, des solutions à des problèmes génériques…
Le code est pour moi quelque chose de vivant, comme un jardin qu’il faut entretenir. Enlever les commentaires faux, c’est comme de retirer les feuilles mortes. Quand je relis du code, j’ai souvent le reflexe de le modifier pour en améliorer l’expressivité, ce qui est différent du travail d’annotation que tu fais sur tes livres, mais qui finalement correspond plus à l’esprit de l’open source non ? Tout le monde peut participer.
Mais là encore je me place dans la position de quelqu’un qui produit le code et non quelqu’un qui le regarde comme on regarde une fourmilières.
Bon aller, je retourne à mon travail de développeur professionnel… 🙂
[Reply]
[…] Après la publication de Littérature du code et la lecture des commentaires à cette note, je me suis demandé s’il y avait des pratiques d’écriture qui évoluaient en s’imprégnant des pratiques du code. […]
bonjour,
(je suis un professionel de la programmation : je suis payé pour produire du code)
je ne comprends pas le rapport entre le fait que le code considéré soit « pro » ou « amateur » et la présence de commentaires inutiles : à mon avis, du bon code est auto-documenté, même si il est produit par un amateur.
en effet, qu’est qui est plus pratique :
——————-
// commentaire qui explique ce qui suit ?
objet.doTheThingWithoutPrecision(arg1)
——————-
——————-
objet.actionMetier(argumentComprehesible)
——————-
à mon avis, la deuxième solution est la meilleure quel que soit le contexte. lorque le code exprime une intention bien précise, quiconque le relit le comprend aisément. nul besoin d’avoir recours aux commentaires, le flux des instructions se comprend bien. Egalement, l’API se lit facilement si les méthodes « parlent »
Enfin, dans des tests unitaires aussi, il vaut mieux des noms de tests qui parlent (testEntreeUtilisateurNonNumerique_Controle_RenvoieErreurSaisieNumeriqueObligatoire)
plutot que des test1 test2 test3 avec un commentaire au dessus.
De plus, les tests unitaires peuvent commenter une API complexe : pour moi, la meilleure façon d’expliquer, c’est de donner des exemples, et c’est ce que permettent els tests unitaires.
[Reply]
J’ai franchement pas lu tout vos commentaires, meme le meilleur des codes devrait etre commente parfois, le code c’est une traduction d’une idee et pour une idee il y’a surement beaucoup de traductions possibles, de l’isomorphe au plus cryptique. Certaines optimisations liees au langage d’implementation ou a un contexte particulier (comme dit dans l’article) sont tres longues a reperees parfois.
Pour l’info il y’a un bouquin assez connu on dirait qui traite du sujet :
http://www.spinellis.gr/codereading/
Et pour conclure je pense que le seul code « non commentable » c’est mini langage specifique interprete car ici pas de projection vers un ensemble de concepts differents. (Oui je suis un futur Lispien =])
[Reply]
@Christian : si, c’est moi ! (grillé)
mais depuis j’ai changé de boulot et je n’ai plus trop le temps d’écrire ce genre d’articles (il m’en reste au moins 2 à écrire…). Je ne perds pas espoir.
ps : désolé pour les exemples de code tout pourris, mais si je colle du « vrai » code sur lequel je travaille tous les jours, cela va être difficile d’expliciter le contexte alentour et j’aurais noyé mon propos.
@fasteez : je pense que si tu as du code qui est complexe et difficile à suivre, alors il faut « cacher » la partie difficile à l’utilisateur en publiant une API facile. TDD peut bien aider pour cela puisqu’il nous permet de réfléchir au « quoi faire » plutot qu’au « comment faire ». De même, au sein de ton implémentation compliquée/complexe, je suis persuadé qu’il y a des moyens pour redécouper le travail, faire parler le code sans commentaire, simplifier l’implémentation. Mais ce n’est pas facile. C’est même très difficile d’écrire du code lisible sans commentaire (mon coach parle de code « beau à pleurer », sacré objectif !)
Merci pour le lien vers le bouquin : ca m’a l’air intéressant !
[Reply]
Un code sans commentaire est un mauvais code,
un bon code n’a pas besoin de commentaire…
[Reply]