# Programmation lettrée

La programmation lettrée (ou programmation littéraire) est une approche de la programmation préconisée par Donald Knuth qui se veut différente du paradigme de programmation structurée des années 1970.
   « Je crois que le temps est venu pour une amélioration significative de la documentation des programmes, et que le meilleur moyen d'y arriver est de considérer les programmes comme des œuvres littéraires. D'où mon titre, « programmation lettrée ».
   Nous devons changer notre attitude traditionnelle envers la construction des programmes : au lieu de considérer que notre tâche principale est de dire à un ordinateur ce qu'il doit faire, appliquons-nous plutôt à expliquer à des êtres humains ce que nous voulons que l'ordinateur fasse.
   Celui qui pratique la programmation lettrée peut être vu comme un essayiste, qui s'attache principalement à exposer son sujet dans un style visant à l'excellence. Tel un auteur, il choisit, avec soin, le dictionnaire à la main, les noms de ses variables et en explique la signification pour chacune d'elles. Il cherche donc à obtenir un programme compréhensible parce que ses concepts sont présentés dans le meilleur ordre possible. Pour cela, il utilise un mélange de méthodes formelles et informelles qui se complètent. »
— Donald Knuth, Literate Programming
Le paradigme de la programmation lettrée, tel qu'il a été conçu par Knuth, s'éloigne dans son écriture de l'ordonnancement imposé par l'ordinateur, et à la place autorise les développeurs à utiliser un ordre imposé par la logique et le fil de leur pensée. Les programmes lettrés sont écrits, dans un langage naturel, comme une exposition ininterrompue de la logique, à la manière d'un essai, dans lequel sont incluses des macros qui masquent les abstractions et la complexité.
La programmation lettrée propose des outils pour obtenir, à partir d'un fichier source, deux représentations : l'une utilisée par un compilateur ou un exécutable, le code « emmêlé », et l'autre lue comme une documentation formatée, qui est dite « tissée » à partir de la source lettrée. Alors que les premiers outils de programmation lettrée étaient spécifiques à chaque langage de programmation, la deuxième génération a produit des utilitaires indépendants des langages et existant hors de ceux-ci.

## Prémices dans les années 1970

Edsger Dijkstra, dans sa conférence Turing, L'humble programmeur (en), avait mentionné qu'un esprit porté sur la rigueur mathématique et une maîtrise exceptionnelle de la langue maternelle étaient deux caractères essentiels qui faisaient un bon programmeur.
En France, Jacques Arsac était réputé dans les années 70 pour ne pas apprécier outre mesure les recours aux ordinogrammes alors à la mode et lui préférer largement le pseudo-code. Claude Pair promouvait, quant à lui, la méthode déductive, très proche de la programmation lettrée.

## Concept

Un programme lettré est une explication de la logique du programme en langage naturel, comme l'anglais, entremêlée de fragments de code source traditionnel (éventuellement de macros). Les macros, dans un fichier source lettré, se présentent comme des titres ou des phrases en langue naturelle, qui décrivent les abstractions créées au moment de résoudre le problème et cachent le morceau de code ou la macro bas-niveau. Ces macros sont similaires aux algorithmes en pseudo-code souvent utilisés dans l'enseignement des sciences informatiques. Ces phrases explicatives deviennent de nouveaux opérateurs, créés à la volée par le programmeur, formant un méta-langage au-dessus du langage de programmation compréhensible par l'ordinateur.
Un préprocesseur analyse les hiérarchies arbitraires, ou les « toiles interconnectées de macros », pour produire un code source compilable. La commande qui fait cela s'appelle (tangle, emmêler) et la commande associée qui produit la documentation s'appelle (weave, tisser). Le préprocesseur permet aussi d'extraire des macros et d'ajouter du contenu à une macro déjà définie à n'importe quel endroit du texte, permettant ainsi de s'affranchir du besoin de garder à l'esprit les restrictions imposées par les langages de programmation traditionnels et d'éviter d'interrompre le flux de pensée.

### Avantages

Selon Knuth, la programmation lettrée permet d'écrire des programmes de grande qualité, car elle force le programmeur à exposer clairement sa pensée cachée derrière le code, rendant les mauvaises décisions de conception plus évidentes. Knuth affirme aussi que la programmation lettrée fournit un système de documentation de premier ordre, qui n'est pas un ajout au code, mais en fait naturellement partie dans un processus d'exposition de la pensée, durant la création du programme. La documentation, partie intégrante de la programmation lettrée, permet à l'auteur de reprendre le fil de son cheminement intellectuel là où il l'avait arrêté, même longtemps après, de même qu'elle permet aux autres programmeurs de comprendre la structure profonde du programme.
La programmation lettrée s'affranchit donc de la documentation traditionnelle, dans laquelle un programmeur présente le code source selon une organisation issue des contraintes du compilateur ou doit en déchiffrer l'intention grâce au code et aux commentaires qui y sont associés. Le méta-langage de la programmation lettrée facilite la pensée, en donnant une vue d'ensemble du code et en augmentant le nombre de concepts que l'esprit peut intégrer. Knuth affirme que la programmation lettrée accroît la qualité du code produit.
Knuth a appliqué la programmation lettrée à grande échelle à sa présentation de TeX, logiciel très utilisé dans le domaine de l'édition scientifique.

### Méconceptions

La programmation lettrée est souvent assimilée à tort à une simple documentation générée à partir d'un seul document source mixant code et commentaires, ou à des commentaires volumineux inclus dans le code. Cette méconception a poussé à considérer les outils d'extraction de commentaires, comme le Plain Old Documentation de Perl, comme des « outils de programmation lettrée ». Cependant, parce que ces outils n'implémentent pas les « toiles de concept abstraits » proposées par les macros en langage naturel, ou ne fournissent pas la possibilité de changer l'ordre du code source, de celui imposé par la machine à celui pratique pour l'esprit humain, ils ne peuvent pas être appelés outils de programmation lettrée telle que la définit Knuth.

## Exemple

Un exemple classique de programmation lettrée est l'implémentation du programme de compte de mots wc d'Unix. Knuth a présenté une version CWEB de cet exemple dans le chapitre 12 du livre Literate Programming. Le même exemple a plus tard été réécrit pour l'outil de programmation lettrée noweb. Cet exemple fournit une bonne illustration des éléments principaux de la programmation lettrée.

### Création de macros

Le morceau de code du programme lettré wc suivant montre comment les phrases arbitraires en langage naturel sont utilisées en programmation lettrée pour créer des macros, qui agissent comme des « opérateurs » dans le langage de programmation lettrée, et masquent les morceaux de code ou les autres macros. La notation de balisage consiste en des doubles chevrons (« <<…>> ») qui indiquent les macros, le signe « @ » indiquant la fin d'une section de code dans un fichier noweb. Le symbole « <<*>> » indique la « racine », le nœud parent duquel l'outil de programmation lettrée va étendre la toile de macros. En réalité, on peut extraire le code source de n'importe quelle section ou sous-section (c'est-à-dire, un morceau de code désigné par « <<nom du morceau>>= », avec le signe égal), et un programme lettré peut donc contenir plusieurs fichiers de code source à extraire.
Notez aussi que le démêlage des morceaux de code peut être fait n'importe où dans le fichier texte de programmation lettrée, et pas nécessairement dans l'ordre où ils sont affichés dans le morceau qui les référence, mais dans celui demandé par la logique, reflétée dans le texte explicatif qui enveloppe le programme complet.

### Le programme comme une toile – les macros ne sont pas que des noms

Les macros ne sont pas la même chose que les « noms de section » dans les documentations habituelles. Les macros de programmation lettrée peuvent masquer n'importe quel morceau de code, et être utilisées dans n'importe quelle structure du langage machine bas niveau, souvent à l'intérieur des opérateurs logiques comme « if », « while » ou « case ». Ceci est illustré par l'extrait suivant du programme lettré wc.
En fait, les macros peuvent se placer dans n'importe quel morceau de code ou d'autres macros, et sont ainsi plus générales que le « découpage » ascendant ou descendant, ou le découpage en sections. Knuth indique que lorsqu'il a réalisé ceci, il a commencé à penser le programme comme une « toile d'araignée » faite de différentes morceaux.

### L'ordre de la logique humaine, pas celle du compilateur

Dans un programme lettré noweb, en plus de l'ordre libre de leurs explications, les morceaux derrière les macros, une fois introduits avec « <<…>>= », peuvent être continués à n'importe quel endroit du fichier en écrivant simplement « <<nom du morceau>>= » et en ajoutant plus de contenu à ceux-ci, comme l'extrait suivant le montre (le signe « + » est ajouté par le formateur du document pour la lisibilité et n'est pas dans le code) :

### Retenir le cours de la pensée

La documentation d'un programme lettré fait partie de l'écriture du programme. Au lieu de commentaires proposés comme des petites notes sur le code source, un programme lettré contient les explications des concepts à chaque niveau, les niveaux les plus bas étant relégués à une place appropriée, ce qui permet une meilleure communication des idées. Les extraits du wc lettré ci-dessus montrent comment l'explication du code et sa source sont entremêlés. Une telle exposition des idées crée un flux de pensée qui se rapproche d'un travail littéraire. Knuth a écrit une « nouvelle » qui explique le code du jeu de stratégie Colossal Cave Adventure.

## Outils

Le premier outil de programmation lettrée publié a été WEB, introduit par Donald Knuth en 1981 pour son système de composition de documents TeX. Il utilise Pascal comme langage de programmation bas niveau et TeX pour la composition de la documentation. Le code source complètement commenté de TeX a été publié dans TeX: The Program, volume B de la série de 5 volumes Computers and Typesetting. Knuth avait déjà utilisé de manière privée un système de programmation lettrée appelé DOC dès 1979. Il a été inspiré par les idées de Pierre-Arnoul de Marneffe. Le programme libre CWEB, écrit par Knuth et Silvio Levy, WEB adapté au langage C et C++, tourne sur la plupart des systèmes d'exploitation et peut produire de la documentation TeX et PDF.
D'autres implémentations du concept de programmation lettrée sont noweb et FunnelWeb, tous deux indépendants du langage de programmation du code source. Noweb est aussi bien connu pour sa simplicité : seulement deux conventions de balisage et deux commandes à invoquer sont nécessaires pour l'utiliser, et permet de formater le texte en HTML plutôt que d'utiliser le système TeX.
FunnelWeb est un autre outil de programmation lettrée qui peut produire de la documentation HTML. Il a un langage de balisage plus compliqué (avec « @ » échappant chaque commande de FunnelWeb), mais a des options plus flexibles.
Nuweb peut traduire un simple fichier de programmation lettrée en n'importe quelle quantité de fichiers sources et utilisant de multiples langages de programmation, et possède une documentation en LaTeX. Il procède en une seule invocation de commande, sans avoir deux commandes séparées pour l'emmêlage et le tissage (« tangle » et « weave »). Il n'est pas aussi extensible que noweb, mais peut utiliser le paquet de listings de LaTeX pour proposer du pretty-printing et le paquet hyperref pour générer des liens dans la sortie PDF. Il a aussi des fonctionnalités de référencement croisé extensibles, incluant des références dans le code généré permettant de retrouver sa position dans la documentation, sous forme de commentaires ainsi que de chaîne de caractères que le code peut utiliser pour reporter son comportement. Vimes est un vérificateur de types pour la notation Z qui montre l'usage de nuweb dans une application pratique. Environ 15 000 lignes de code source nuweb sont extraites en environ 15 000 lignes de C/C++ et plus de 460 pages de documentation. (voir les liens externes.)
Molly est un outil de programmation lettrée écrit en Perl, dont l'objectif est de moderniser et d'étendre la programmation lettrée avec le « pliage HTML » et les « vues virtuelles » du code. Il utilise le langage de balisage de noweb pour les sources lettrées. (voir les liens externes.)
Codnar est un outil de programmation lettrée inversé disponible sous forme de Gem Ruby (voir les liens externes). Au lieu d'extraire le code source de la documentation, le document lettré est extrait du code source. Ceci permet à ces fichiers source d'être édités et maintenus normalement. L'approche est similaire à celle utilisée par des outils populaires de documentation d'API, comme la JavaDoc. Ces outils, cependant, génèrent une documentation de référence, tandis que Codnar génère une description linéaire et narrative du code, similaire à celle créée par les outils de programmation lettrée habituels. Codnar peut coexister avec les outils de documentation d'API, permettant à un manuel de référence et à une explication narrative d'être générés à partir de la même collection de fichiers source.
Leo est un éditeur de texte structuré qui supporte de manière optionnelle les langages de balisage de noweb et CWEB. L'auteur de Leo mélange deux approches différentes : premièrement, Leo est un éditeur de texte structuré, ce qui aide la gestion de larges textes; ensuite, Leo inclut des idées de programmation lettrée, qui dans sa forme la plus pure (c'est-à-dire, la manière dont les outils de Knuth et d'autres, comme noweb, l'utilisent) est possible avec un certain degré d'inventivité et l'utilisation de l'éditeur d'une manière pas exactement prévue par son auteur (dans des nœuds @root modifiés). Cependant, ceci et d'autres extensions (les nœuds @file) rend la structuration du programme et la gestion du texte facile et d'une certaine manière similaire à la programmation lettrée.
Le langage de programmation Haskell possède un support natif de programmation semi-lettrée, inspiré par CWEB mais avec une implémentation plus simple. Quand l'objectif est une sortie TeX, on écrit un fichier LaTeX où le code est marqué par un environnement donné ; LaTeX peut être configuré pour gérer cet environnement, pendant que le compilateur Haskell cherche les bons marqueurs pour identifier les expressions Haskell à compiler, retirant la documentation TeX comme si elle était en commentaire. Cependant, comme décrit plus haut, ce n'est pas de la programmation lettrée dans le sens entendu par Knuth. La nature fonctionnelle et modulaire de Haskell rend la programmation lettrée directement dans le langage plus aisée, mais n'est pas aussi puissante que celle des outils WEB où « tangle » peut réorganiser le code dans un ordre arbitraire.