Martin (arp242) vient d’hériter d’un projet legacy. Son premier réflexe — avant même de lire le code — a été de lancer une commande :
git log --no-merges --format=format:'%b' | sed '/^$/d' | wc -lRésultat : 295. En treize ans, tous les messages de commit de ce projet additionnés tiennent sur 295 lignes. Retirez les commits Dependabot, les « revert commit » et les « fix typo », il en reste 167. Une ligne par mois, en moyenne.
Aucune documentation. Presque aucun commentaire. Et trois semaines de passation avec le développeur précédent, dont la qualité de communication rivalisait avec celle des messages de commit. « Je n’ai jamais aussi bien compris Jack Bauer quand il essayait d’obtenir des informations par des moyens extrêmes, » écrit Martin. « J’aurais dû essayer. »
Les deux faces de la barrière
Le principe de la barrière de Chesterton, en génie logiciel, est connu : vous tombez sur un bout de code étrange, vous voulez le virer, mais avant de le faire, vous devez comprendre pourquoi il est là — il protège peut-être d’un danger que vous ne soupçonnez pas. Chesterton, dans sa formulation originale, disait qu’un réformateur ne doit pas abattre une barrière avant de pouvoir répondre à la question : « pourquoi a-t-elle été construite ici ? »
Martin en donne l’envers : le doigt d’honneur de Chesterton.
« Oui, on a fait tous ces trucs bizarres, mais on n’a pas l’intention d’expliquer à qui que ce soit pourquoi. Allez vous faire foutre. »
Le sens d’une barrière dépend de son contexte. Quand le contexte disparaît — avec les messages de commit, les commentaires et la documentation — la barrière n’est plus une protection, c’est une malédiction. Le développeur qui arrive après se retrouve face à un vestige sans épitaphe : un fatras indéchiffrable qu’il faut soit archéologiser pendant des mois, soit dynamiter au risque de tout casser.
Trois commits toxiques
Martin ne propose pas de taxonomie systématique, mais son récit esquisse trois patterns particulièrement destructeurs.
« fix page A » — le titre vide. Des modifications massives, et pour seul résumé, trois mots qui ne disent rien. Le corps du message est vide. Celui qui passe après doit reconstituer l’intention à coups de diff, avec une précision qui vaut à peu près celle de la lecture d’os.
Le commit WIP — le chantier abandonné. Des refactorings inachevés traînent dans la base de code. Des carcasses de fonctionnalités disparues n’ont jamais été nettoyées. Des fonctions entières ont été écrites mais jamais reliées, jamais utilisées. Ce ne sont pas des bugs — c’est pire qu’un bug : un bug, au moins, quelqu’un le signale.
Le « pas besoin » — le Gap de Chesterton. Martin introduit un concept symétrique : si la barrière de Chesterton, c’est « un mur construit sans explication », le Gap de Chesterton, c’est « un vide qu’on s’acharne à combler » — des couches d’abstraction là où personne n’en demandait, de l’over-engineering pour un besoin futur qui n’existera jamais.
Ces trois patterns réunis forment un désastre archéologique du code : l’héritier ne doit pas seulement comprendre ce que le code fait, mais reconstituer pourquoi il le fait et ce que son prédécesseur comptait en faire.
Trois questions
Martin donne un cadre pragmatique pour le message de commit. Trois questions :
- Qu’as-tu changé ?
- Pourquoi l’as-tu changé ?
- Pourquoi cette solution est-elle la bonne ?
« Implement new feature X » suffit parfois. Mais la plupart du temps, il y a toujours quelque chose à dire — ne serait-ce qu’expliquer un paramètre, justifier une valeur seuil, mentionner une alternative écartée.
Pas besoin de belles phrases. Pas besoin d’un traité philosophique. Oublier un détail n’est pas un drame (mais le noter, c’est mieux). La ligne rouge, c’est : mets quelque chose. N’importe quel effort, même bancal, est infiniment supérieur au vide.
Le verdict de Martin est sans appel : « Écrire un message de commit n’est pas une option. Ça fait partie du travail. Ne pas le faire, c’est ne pas finir son boulot. »
Consensus sur Lobsters
Sur Lobsters, l’article a recueilli 106 points et une quasi-unanimité. Un commentateur écrit : « J’ai passé cinq ans à réparer ce genre de bases de code aux quatre coins du monde. Je dors avec Working Effectively with Legacy Code sous l’oreiller. »
david_chisnall tape là où ça fait mal — la revue de code : « Le plus grand bénéfice de la code review, c’est qu’elle t’oblige à écrire tout le contexte que tu n’avais pas formulé. Ce que tu n’arrives pas à expliquer, ce que le reviewer ne comprend pas — ça finit en commentaire. »
Un scénario revient en boucle : tu hérites du code d’un collègue parti. Impossible de poser la moindre question. Le log de commit est ta dernière source d’information. S’il est vide, tu n’es plus face à du code — tu es face à un site archéologique dont toutes les inscriptions ont été méthodiquement grattées.
Pourquoi c’est encore plus critique aujourd’hui
Les outils de codage assisté par IA — Codex, Claude Code, Copilot — accélèrent la production de code d’un facteur dix. Mais les messages de commit ne s’écrivent pas tout seuls. Pire : les messages auto-générés du style « Add files via upload » ou « Update code » sont plus dangereux que le silence, parce qu’ils fabriquent l’illusion d’une documentation.
Un projet de treize ans avec 295 lignes de commit, à l’ère de la programmation assistée par IA, ne deviendra pas plus rare. Il deviendra la norme. Produire du code est plus rapide que d’écrire un commentaire, et l’IA ne va pas décider à votre place que « tiens, ici, il faudrait expliquer pourquoi cette structure de données plutôt qu’une autre ».
Martin conclut : « Si tu n’écris rien, tu fais un doigt d’honneur à tous ceux qui passeront après toi. » La métaphore est rude. Mais elle est juste. Un message de commit n’est pas un mémo pour soi-même. Il s’adresse à toi dans trois ans, au collègue qui reprend ton code, à celui qu’on réveille à deux heures du matin pour une régression en production.
Cet article s’appuie sur des informations publiques et des discussions communautaires. Si vous avez une expérience directe sur ce sujet, vos corrections et compléments sont bienvenus.