Un mot laissé sur le frigo pour dire où sont les clés, ça se lit en deux secondes. Une ligne de commentaire perdue dans un vieux script Python, ça peut prendre une soirée entière à se faire comprendre — et pourtant c'est exactement le même geste : laisser une trace pour la version de soi qui aura tout oublié. J'ai mis un long moment à l'admettre, moi qui apprends Python en autodidacte sur mes soirées, persuadée au début que commenter son code était réservé à ceux qui doutaient d'eux-mêmes. Aujourd'hui, mes commentaires sont devenus la partie la plus utile de toute mon organisation d'apprentissage, bien avant n'importe quelle astuce de syntaxe.
Rouvrir un vieux fichier, c'est parfois ne plus reconnaître son écriture
Le week-end dernier, j'ai rouvert un petit script que j'avais écrit pour trier mes photos de vacances par dossier. Ça ne m'a pas pris longtemps pour comprendre que je regardais le travail d'une inconnue. Une fonction s'appelait range_2, une variable s'appelait donnees_bis, et je n'avais pas la moindre idée de ce qui distinguait donnees_bis de la donnees tout court qui traînait trois lignes plus haut. Le code, en lui-même, ne racontait rien de mes intentions du moment où je l'avais écrit.
Pendant mes premières semaines de python-débutante, je pensais sincèrement qu'ajouter des commentaires revenait à admettre qu'on n'avait pas vraiment compris ce qu'on écrivait. Un soir entier passé à démêler les opérateurs mathématiques en python m'avait convaincue que l'effort fourni suffirait, à lui seul, à graver la logique dans ma mémoire pour de bon. Cette idée-là a tenu bon jusqu'à ce que la réalité d'une vie chargée entre travail et obligations diverses me prouve le contraire, plusieurs fois de suite.
Le projet trop ambitieux qui a fini à la poubelle
En rentrant du marché du Brézet un dimanche, un collègue m'avait convaincue de voir plus grand : plutôt que des petits scripts isolés, pourquoi ne pas construire tout de suite une vraie application avec plusieurs fichiers qui se parlent entre eux ? L'idée m'avait emballée sur le trajet du retour. Une fois devant mon clavier, j'ai vite compris que je n'avais ni le vocabulaire ni les réflexes pour tenir un projet pareil : je perdais le fil entre les fichiers, je ne savais plus où j'avais défini quoi, et au bout de quelques soirées, j'ai fini par tout laisser de côté, découragée.
Ce fiasco m'a au moins appris une chose : sans note nulle part pour expliquer pourquoi tel fichier appelait tel autre, je naviguais à l'aveugle. Revenue à des scripts plus modestes, un seul fichier à la fois, j'ai commencé à glisser une phrase ici ou là pour me rappeler où j'en étais, presque comme un pense-bête laissé sur le plan de travail avant de sortir.
Et si le déclic tenait dans un seul caractère ?
La bascule s'est faite un soir où j'ai relancé un script mis de côté depuis un moment, un simple convertisseur que j'utilisais pour calculer mes économies. J'avais laissé, sans trop y penser, une ligne qui commençait par le symbole #, expliquant pourquoi je divisais tel nombre par tel autre. J'ai lancé le script en m'attendant au pire. Le terminal a affiché exactement le texte que j'espérais, au mot près, et je suis restée silencieuse devant l'écran pendant deux bonnes secondes, presque suspicieuse de ma propre réussite.
Ça fait maintenant une dizaine de semaines que je prends cette habitude au sérieux, et rouvrir un vieux fichier n'est plus le petit drame que c'était au printemps. Ce n'est pas une révélation soudaine, plutôt une habitude qui a fini par s'installer soir après soir : je laisse un mot pour la Pauline qui aura oublié, pas pour prouver quoi que ce soit à qui que ce soit.
Commenter chaque ligne, ou comment se compliquer la vie
J'ai vite basculé dans l'excès inverse : commenter absolument tout, y compris des lignes qui n'avaient besoin d'aucune explication. Le problème, c'est qu'un commentaire mal entretenu devient un mensonge silencieux. Si je modifie une variable, change les bornes d'une boucle, ajuste une condition ou touche à ce que récupère un input() mais que j'oublie de mettre à jour la phrase juste au-dessus, je me retrouve avec un texte qui raconte une tout autre histoire que celle du code en dessous — et repérer ce genre de décalage, une fois perdue dans un bloc mal indenté, prend un temps fou.
Depuis, j'essaie d'expliquer le pourquoi plutôt que le quoi. Écrire qu'une ligne ajoute un élément à une liste ne sert à rien si le code le montre déjà tout seul ; expliquer pourquoi cet élément précis doit être ajouté à cet endroit précis, ça, c'est utile. C'est un peu comme noter au dos d'une recette pourquoi on a remplacé un ingrédient plutôt que de réécrire toute la recette : seule l'intention mérite d'être conservée.
Les petites habitudes que je me suis données pour organiser mes commentaires
J'ai fini par adopter quelques réflexes empruntés aux conventions que les développeurs appellent la PEP 8, sans prétendre les suivre à la lettre. J'évite par exemple d'étirer une ligne de commentaire trop loin vers la droite de l'écran, pour ne pas avoir à faire défiler l'affichage juste pour lire une explication. J'ai aussi découvert les docstrings, ces commentaires entre triples guillemets qu'on place au début d'une fonction pour dire ce qu'elle attend en entrée et ce qu'elle renvoie à la fin — bien plus lisible qu'une multitude de # éparpillés. Je m'en sers aussi pour noter ce que je n'ai pas encore réussi à gérer, comme apprendre à utiliser try except pour que le programme ne plante pas si je tape une lettre à la place d'un chiffre.
Une voisine qui s'est mise à l'apiculture sur son balcon note scrupuleusement l'activité de ses ruches d'une saison à l'autre, pour ne pas repartir de zéro chaque printemps ; mes commentaires jouent exactement ce rôle-là pour mes scripts. J'y note pourquoi tel dictionnaire regroupe telles clés plutôt que d'utiliser deux listes séparées, pourquoi tel message d'erreur m'avait complètement perdue la première fois, ou pourquoi j'ai fini par importer tel module plutôt que d'écrire la fonction moi-même. Même l'installation de Python sur mon ordinateur, ce tout premier soir où je ne comprenais rien à l'invite de commandes, mériterait sans doute deux lignes d'explication quelque part.
Commenter, c'est apprendre une deuxième fois
L'autre soir, je me suis attaquée à un petit jeu de hasard, rien de plus qu'un tirage au sort entre trois issues possibles. En commentant chaque étape du tirage pour m'y retrouver plus tard, je me suis rendu compte en cours de route qu'il manquait une condition entière — le jeu ne gérait pas le cas d'une égalité. Sans l'effort de mettre des mots sur ce que chaque bloc était censé faire, j'aurais sans doute mis un long moment à repérer le trou.
Mes commentaires ne sont pas beaux : un vrai développeur rirait sûrement devant une note du genre # ici je m'assure de ne pas mélanger les torchons et les serviettes. Mais la leçon que je retiens de ces dix semaines, c'est qu'un commentaire n'a jamais pour but de prouver qu'on maîtrise son sujet — il sert uniquement à faire gagner du temps à la personne qui rouvrira le fichier, même si cette personne, c'est soi-même dans quelques mois. Reste à savoir si j'appliquerai la même discipline à mes f-strings, où les chaînes de caractères et les variables s'accumulent encore un peu trop vite à mon goût.