Littérature de code

by Christian on 7 janvier, 2008

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 :

  1. 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.
  2. 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.
  3. 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.

Print Friendly
Signaler sur Twitter

{ 15 comments… read them below or add one }

Aurélien janvier 7, 2008 à 12:03

Un code sans commentaire est un mauvais code,
un bon code n’a pas besoin de commentaire…

Répondre

Christian janvier 7, 2008 à 12:07

bel aphorisme 🙂

Répondre

pouype janvier 7, 2008 à 2:49

Je suis assez d’accord avec Aurélien.

« Un bon code n’a pas besoin de commentaire »

Répondre

Christophe janvier 7, 2008 à 3:20
Etienne Charignon janvier 7, 2008 à 6:14

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.

Répondre

Christian janvier 7, 2008 à 10:26

Merci pour cet excellent et enrichissant commentaire Étienne. 🙂

Tu me diras si je me trompe, mais il me semble que ton commentaire se place dans un contexte résolument professionnel.

Tous tes arguments sont valides et me parlent.

Mais il faut que je précise que ma pratique et mon intérêt pour le code ne sont pas professionnels : ce n’est pas encore aujourd’hui que quelqu’un va accepter de me payer pour mes compétence de développeur.

Il est donc évident que mon discours est celui de l’amateur, celui qui ne pratique que parce qu’il a du plaisir à apprendre et à pratiquer. Alors forcément, les vertus pédagogques et les considération à plus long terme sont privilégiées.
Il est vrai que je vois mal un code développé pour un client qui contiendrait des commentiares de deuxième ou de troisième niveau. Cela ne ferait pa sérieux. D’ailleurs on ne retrouve ce type de pratique que dans la commuauté libre( ou en tout cas très majoritairement).

Pour la pour la petite anecdote, Aurélen Pelletier me disait aujourd’hui qu’en faisant une recherche sur « fuck » les commentaires des releases du code de linux on pouvait avoir un bon aperçu des difficultés rencontrées par les developpeurs :-).
Mais là, on voit qu’on n’est déjà moins dans le même environnement et contexte que celui qui transparaît dans ton commentaire.

Voilà, tout çà pour dire que je suis entièrement d’accord avec tes propos tout en croyant à une pratique du code qui ne soit pas réservé à un contexte et un environnement uniquement et toujours professionnel (qui a des enjeux et des impératifs à cours terme que n’a pas un amateur).

J’aimerai terminer ma réponse en faisant un parallèle avec la littérature, et justifier pourquoi « La littérature du code » a été justement le titre de cette note :
On peut avoir accès aux notes de travail et aux manuscrits d’un écrivain : c’est une source d’informations parfois importante dans l’analyse et la compréhension de l’oeuvre. Bien sûr, tout le monde n’aimerait pas lire un roman avec les annotations de l’auteur dans la marge et les ratures dans le texte. Cà c’est pour la première lecture, mais à la seconde lecture ? N’aimerait-on pas découvrir les coulisses de la création et les échaffauvages qui ont contribués à sa conception ?
Personnellement Je n’ai vraiment aimé lire qu’à partir du moment où, un jour, j’ai désacralisé la page du livre en commençant à souligner et grifonner les pages, pour en faire un lieu de travail et d’interaction avec l’oeuvre.
C’est donc cette idée que je veux bien défendre : celle qui consiste à croire que le code est une chose qui est tellement importante dans notre modernité que l’on doit pouvoir le rendre disponible à une plus grande majorité d’amateurs qui n’en seront peut-être jamais (mais qui sait ?) les professionnels.

On peut bien balayer d’un revers de manche les commentaires en disant que tout cela n’est que « littérature », mais c’est pourtant aussi cette littérature qui me fait aimer et découvrir le code.

J’espère que tes lumières viendront éclairer plus souvent ce blog grace à tes commentaires. 🙂

Répondre

Christian janvier 8, 2008 à 11:30

@Christophe : merci pour les liens.
Chacun fera ses recherches 🙂

Répondre

Etienne Charignon janvier 8, 2008 à 1:16

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… 🙂

Répondre

Christian janvier 8, 2008 à 2:16

Bon code !
Et n’oublie pas de mettre un lien vers ce billet dans tes commentaires de code 😉

Répondre

Hubert Guillaud janvier 10, 2008 à 11:18
Christian janvier 11, 2008 à 11:03

Bon rebond, merci Hubert.

Répondre

JP mars 7, 2008 à 3:40

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.

Répondre

Christian mars 7, 2008 à 8:12

Tu as raison, il est toujours souhaitable d’avoir des méthodes qui « parlent », bien qu’un commentaire pour commenter une méthode ou une ligne de code n’est que le cas le plus « discret » du commentaire.
Un commentaire peu éclairer des dizaines de lignes de code à la fois.

Et sinon, c’est pas toi qui faisait des billets sur le Jazz ?

Répondre

fasteez mars 12, 2008 à 9:44

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 =])

Répondre

JP mars 12, 2008 à 4:02

@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 !

Répondre

Leave a Comment

{ 1 trackback }

Previous post:

Next post: