- La programmation lettrée (Literate Programming), qui tisse le code et son explication en langage naturel dans un même récit, n’a pas été largement adoptée en raison du fardeau consistant à maintenir en parallèle le code et la documentation, mais les agents de codage IA peuvent éliminer ce travail central
- Avec
org-babel d’Org Mode dans Emacs, il est possible de faire de la programmation lettrée multilingue, mais dans les grands projets, la contrainte du processus d’extraction du code source (tangling) en limite l’usage
- En demandant à un agent de rédiger un runbook basé sur un fichier Org, on obtient un workflow où l’intention est développée dans l’explication, où les blocs de code peuvent être exécutés de façon interactive, et où les résultats sont enregistrés dans le document
- Comme l’agent gère automatiquement la synchronisation entre explication et code ainsi que le tangling, il n’est plus nécessaire de réécrire les explications à chaque modification du code, tout en exploitant les capacités de traduction et de résumé dans lesquelles les LLM excellent
- À mesure que le rôle des ingénieurs évolue de l’écriture vers une activité centrée sur la lecture du code, la question clé devient la praticité d’une base de code narrative maintenue par des agents
Concept et limites de la programmation lettrée
- La programmation lettrée (Literate Programming) consiste à mêler le code et son explication en langage naturel afin qu’un lecteur sans connaissance préalable puisse lire la base de code comme un récit et en comprendre le fonctionnement
- Le concept est séduisant, mais dans la pratique il impose le poids de maintenir deux récits parallèles — le code lui-même et son explication — ce qui est la raison fondamentale qui en a limité l’adoption
- Dans la pratique, la forme la plus répandue est celle des notebooks Jupyter dans la communauté data science, où explications, calculs et résultats s’affichent ensemble dans le navigateur
Emacs Org Mode et la programmation lettrée
- Org Mode d’Emacs prend en charge la programmation lettrée multilingue via le package
org-babel, avec la possibilité d’exécuter n’importe quel langage et de capturer les résultats dans le document
- Cela reste toutefois un usage de niche, réservé à un petit nombre d’utilisateurs passionnés
- Si l’on utilise un fichier Org comme source de vérité d’un grand projet logiciel, le code source devient en pratique une sortie compilée, et il faut l’extraire (« tangle ») puis le déployer à destination après chaque modification
- Cela peut être automatisé, mais si l’utilisateur ou l’agent modifie directement le vrai code source, il est facile qu’il soit écrasé au prochain tangle
Schémas d’usage avant les agents
- L’idée n’a pas été abandonnée avant l’arrivée des LLM, car elle donnait déjà des résultats suffisants pour la gestion de configurations personnelles
- Un modèle d’usage d’Org Mode pour les tests manuels et la prise de notes : au lieu de la ligne de commande, on écrit et exécute les commandes dans l’éditeur, on les modifie jusqu’à ce que chaque étape soit correcte, puis on enregistre les résultats sur place
- « Si l’on combine la prise de notes et l’exécution des tests, les notes sont générées gratuitement une fois les tests terminés »
Un nouveau workflow avec les agents
- Des agents de codage comme Claude ou Kimi comprennent bien la syntaxe d’Org Mode, et Org est un langage de balisage tolérant que les LLM manipulent très bien
- L’ampleur de la syntaxe d’Org Mode est un inconvénient pour les humains, mais ce n’est pas un problème pour les modèles de langage
- Lors d’un test fonctionnel, si l’on demande à l’agent de rédiger un runbook Org :
- l’explication contient la réflexion du modèle sur l’intention de chaque étape
- les blocs de code, après relecture, peuvent être exécutés de manière interactive un par un ou dans leur ensemble comme un script
- les résultats sont enregistrés sous le code, comme dans un notebook Jupyter
- On peut modifier l’explication puis demander au modèle de mettre à jour le code, ou modifier le code puis laisser le modèle refléter ce sens dans l’explication, ou encore laisser l’agent modifier les deux en même temps
- Le problème du maintien de récits parallèles disparaît
Le travail clé que les agents éliminent
- En confiant le tangling à l’agent, le problème de l’extraction du code est lui aussi résolu
- Via un fichier
AGENTS.md, on peut demander à l’agent de traiter les fichiers Org comme source de vérité, de toujours rédiger des explications et d’exécuter le tangle avant exécution
- L’agent sait très bien faire tout cela et ne se fatigue jamais de réécrire l’explication après une modification du code
- Les agents suppriment ainsi le surcroît de travail fondamental qui empêchait la programmation lettrée de se généraliser, en mettant à profit les capacités de traduction et de résumé dans lesquelles les LLM excellent le plus
Bénéfices attendus
- La base de code peut être exportée dans différents formats pour en faciliter la lecture
- C’est particulièrement important si le rôle principal des ingénieurs se déplace de l’écriture vers la lecture
- Même si cela n’est pas étayé par des données, on peut supposer que la qualité du code généré pourrait aussi s’améliorer, car un récit expliquant l’intention de chaque bloc de code apparaît dans le contexte avec le code lui-même
- Cela n’a pas encore été essayé à grande échelle sur une base de code importante et complète, et est pour l’instant utilisé dans des workflows de test et de documentation de processus manuels
Limites d’Org Mode et alternatives
- Le format Org est étroitement intégré à Emacs, ce qui constitue une contrainte, et l’idée de longue date est qu’Org devrait sortir d’Emacs
- On aimerait recommander Markdown comme alternative, mais Markdown manque de mécanismes pour inclure des métadonnées
- Le concept de Properties d’Org Mode permet de manipuler les documents de manière programmatique en Emacs Lisp, et désormais les LLM peuvent même écrire des fonctionnalités sur mesure pour ces documents en Emacs Lisp dans la section file variables
- Markdown n’a pas l’équivalent des header arguments d’Org Mode pour spécifier les détails d’exécution des blocs de code, comme l’emplacement d’exécution ou une machine distante
- Ce qui est enthousiasmant, ce n’est pas l’implémentation spécifique d’Emacs, mais l’idée elle-même
Question centrale
- « Grâce aux agents, peut-il devenir pratique de disposer d’une base de code de grande taille qui se lit comme un récit, tout en laissant une machine infatigable maintenir la synchronisation entre modifications du code et explications ? »
2 commentaires
Commentaires Hacker News
Je pense que la solution la plus simple consiste à faire en sorte que le LLM laisse lui-même ses propres commentaires
Ainsi, quand le LLM relit ensuite le code, il peut s’appuyer sur ses propres commentaires, qui jouent en quelque sorte le rôle d’une mémoire longue juste-à-temps (just-in-time memory)
Faire écrire un résumé dans
<summary>, les raisons et le contexte dans<remarks>, les contraintes dans<params>, et limiter au minimum les commentaires en ligneCela permet aussi, lors de la review d’une PR, de voir directement le raisonnement du LLM dans
<remarks>, et donc de repérer facilement les points qu’il a mal compris par rapport à l’intentionAu final, ils polluent leur propre contexte avec des informations inutiles et dégradent encore leur compréhension
On est encore loin d’un niveau humain de littératie (literacy)
Mais si c’est précisément sur ce type de commentaires que le LLM bute quand il relit le même code, alors ils ont peut-être en réalité de la valeur
Ces commentaires servent donc à préserver cette mémoire
Je pense que les langages de programmation sont apparus parce que le langage naturel est ambigu
Donc les commentaires de code finissent eux aussi par être ambigus, et comme ils ne sont pas exécutés, ils vieillissent vite
Les LLM sont forts pour traduire du code, mais j’ai toujours l’impression qu’ils ont du mal à convertir des prompts en langage naturel en code
Un bon code doit exprimer clairement son intention, et avoir beaucoup de commentaires peut aussi être le signe d’une mauvaise qualité du code
Mais un bon logiciel doit aussi inclure une bonne documentation
La programmation lettrée consiste davantage à écrire des explications qu’à détailler l’implémentation
Le code définit étroitement le « comment », alors que le langage naturel peut exprimer le « quoi », en laissant au LLM la possibilité de proposer une meilleure méthode
Il faut des informations redondantes pour détecter et corriger les erreurs
Ils ne font qu’imposer des règles qui réduisent la liberté d’interprétation
Parfois, la métaphore ou l’ambiguïté sont même des modes d’expression plus appropriés
Si on leur fournit du code d’exemple et de la documentation comme modèle, les hallucinations (hallucination) diminuent
Des recherches montrent que des commentaires dans un style de programmation lettrée aident les humains à mieux comprendre le code
Des chercheurs de Google ont testé si des LLM pouvaient mettre à jour ce type de commentaires, et si cela améliorait la compréhension humaine
Leur conclusion est que les commentaires au niveau des blocs qui expliquent l’intention sont les plus efficaces
(Voir : article arXiv 2024 "Natural Language Outlines for Code")
Un phénomène intéressant récemment, c’est qu’avant, les gens rechignaient à écrire des README ou des documents d’architecture pour les humains
Mais dès qu’on dit que c’est pour les LLM, ils deviennent bien plus motivés
Mais les LLM consultent la documentation à chaque tâche, donc la motivation à documenter devient bien plus forte
Les messages de commit, les traces comme les ADR, les humains ne les regardent pas, mais les LLM lisent tout
Au final, ces habitudes aident aussi les nouveaux arrivants humains
Le code n’a pas besoin que la documentation soit exacte pour fonctionner
C’est pourquoi on a souvent intérêt à regarder directement le code plutôt que la documentation
Je pense que la combinaison d’une programmation lettrée légère et de langages guidés par les conventions convient bien à l’ère des agents
Des langages comme Go, avec une compilation rapide et un guide de style clair, sont bien adaptés
Si on demande à un agent de s’appuyer sur le Google Go Style Guide lorsqu’il écrit du code, on obtient des résultats plutôt bons
(Voir : anecdote liée à Rob Pike)
Comme les LLM sont des modèles de langage, il vaut vraiment la peine d’investir dans une écriture claire
Sans aller jusqu’à la programmation lettrée, de bons noms, des docstrings, des signatures de type et des commentaires qui expliquent le “pourquoi” sont importants
Au fond, l’enjeu est de créer des schémas de communication utiles à la fois pour les humains et pour les LLM
Une documentation qui explique la structure d’ensemble au niveau du fichier, du répertoire et du projet est particulièrement importante
Mais comme ces concepts s’étendent sur plusieurs fichiers, la question de savoir où les écrire et celle de la synchronisation documentation-code posent toujours problème
Depuis dix ans, j’écris presque tout mon code dans un style de programmation lettrée
J’ai créé nbdev pour gérer ensemble code, documentation et tests à partir de notebooks
Plus récemment, j’ai créé un outil appelé Solveit, qui intègre des LLM et est utilisé dans toute l’entreprise
(lien Solveit)
La programmation lettrée est aussi utile pour des tâches autres que la programmation
Ajouter une courte démo ou quelques captures d’écran serait une bonne idée
L’idée d’utiliser des LLM pour détecter automatiquement les écarts entre les commentaires et le code est intéressante
La documentation finit inévitablement par diverger du code avec le temps, donc pouvoir détecter cela automatiquement aurait une grande valeur
On pourrait même créer une startup autour de ça
Les changements commencent par une PR de documentation, puis les développeurs les répercutent dans le code
Lors de la review, la documentation et le code sont affichés côte à côte pour être vérifiés
Le système est aussi conçu pour permettre l’exploration du contexte via des liens entre documents
Ex. : GitHub gh-aw, Continue.dev
La structure en paire du code de test et du code de production est utile, un peu comme la comptabilité en partie double
Les tests expliquent l’intention du code, et le code complète le sens des tests
En review, si un côté est confus, on peut regarder l’autre
L’inconvénient est l’augmentation du volume de code, mais le gain de lisibilité en vaut la peine
J’ai moi aussi récemment écrit sur le codage fondé sur l’intention, et cela rejoint cette discussion
(lien du blog)
Le point important est qu’on peut transformer une base de code en différents formats plus faciles à lire
À l’avenir, même des non-spécialistes seront plus proches du code, et l’inclusion du langage naturel aidera beaucoup leur productivité et leur apprentissage
Wikipédia - programmation lettrée
> La programmation lettrée (literate programming) est une méthodologie de programmation qui met l’accent sur la création d’un code facile à comprendre pour les humains, plutôt que simplement sur la production d’un code compilable par un ordinateur. Autrement dit, l’objectif est de programmer comme on rédige un document destiné à être lu et compris par des personnes. Comme son but est de « rendre le code lisible comme une œuvre littéraire », on lui a donné le nom de « programmation lettrée ».