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.