Drôle, le deuxième lien sur la discussion, c'est vieux de vingt ans mais j'y avais participé!
Comme aujourd'hui, je ne devais pas être convaincu par la machine à gaz du literate programming, qui était le sujet initial, et j'étais parti sur une façon pragmatique de générer de la doc à partir du code (ce qui n'est pas du literate programming).
Bref, je ne sais pas ce qu'est le literate programming, mais je vois un point commun avec bbt : la documentation contient des tests, avec une description malgré tout formelle, au milieu d'un texte libre.
Et une différence : il y a bien un mélange entre formel et informel (Donald Knuth parle de la nécessité d'avoir les deux pour que ce qu'il y a à comprendre rentre bien dans le crâne du lecteur). Mais sur la partie formelle (c'est à dire en gros les steps) on essaie d'être en anglais, aussi lisible que la partie informelle.
Ce qui a bien changé pour moi depuis cette discussion d'il y a 20 ans, c'est que j'ai réalisé à quel point l'exercice de génération de documentation à partir du code était vain.
Je ne lis jamais ces docs. Déjà à l'époque, tout les IDE (moi j'étais sous emacs) permettaient de sauter directement à la déclaration de la fonction truc, ou se trouvaient les commentaires permettant de générer la doc. Donc la doc ne servaient à rien.
Au contraire, les tags mis dans les commentaires pour effectuer la génération viennent rendre la code moche et moins lisible. C'est pourquoi je faisais l'apologie de NaturalDocs à l'époque (et de Markdown maintenant) : embellir, OK, mais l'original doit rester lisible, tant que ce sera la que l'on travaillera en premier lieu.
La doc la plus intéressante contient justement ce qui ne figure pas dans le code, ce que le code ne peut pas transcrire (cf. le niveau sémantique dont je parlais plus haut). Et, petit parallèle avec literate programming, il n'y a pas forcément d'endroit idéal dans le code pour mettre ces infos en commentaire.
Des choix d'architecture, par exemple, pourquoi les mettres dans un source plutôt qu'un autre? Leurs place n'est en fait pas dans un source, mais dans un doc qui s'appele "choix d'architecture".
je n'utilise plus de header systématique de fichier ou de fonction, qui stimule l'écriture de commentaires à 80% insipide. Si j'ai quelque chose à dire, je le dis. Dans la spec si ça concerne l'utilisateur, dans le body si ça concerne le mainteneur.
Donc, j'essaie :
1. d'écrire un code clair (quel pied quand il n'y a pas besoin de commentaire!)
2. je mets des commentaires là ou il faut, et pas plus.
3. je n'extrait plus rien du code, si tu veux voir le code, ben va voir le code!
Mon code est beau :-), il n'a rien à cacher et n'a pas besoin de maquillage. Ton IDE est génial, tu peux naviguer avec, pas besoin d'html.
4. la documentation qui m'intéresse le plus sur un outil, c'est celle qui m'explique ce que je peux faire avec. Or, et là on rejoint le sujet, cette doc donne généralement des exemples, des limitations et des cas d'erreurs, que l'on retrouve également dans les tests.
Donc, terminé d'écrire deux fois les choses : maintenant, avec bbt, j'écris un seul des deux.
Mais peut-être que dans encore 20 ans je dirai tout autre chose :-)
[^] # Re: Et l’approche inverse ?
Posté par Lionel Draghi (site web personnel) . En réponse au journal Documenter ou tester, il faut trancher (j'ai pas trouvé de rime avec choisir...). Évalué à 1.
Drôle, le deuxième lien sur la discussion, c'est vieux de vingt ans mais j'y avais participé!
Comme aujourd'hui, je ne devais pas être convaincu par la machine à gaz du literate programming, qui était le sujet initial, et j'étais parti sur une façon pragmatique de générer de la doc à partir du code (ce qui n'est pas du literate programming).
Bref, je ne sais pas ce qu'est le literate programming, mais je vois un point commun avec bbt : la documentation contient des tests, avec une description malgré tout formelle, au milieu d'un texte libre.
Et une différence : il y a bien un mélange entre formel et informel (Donald Knuth parle de la nécessité d'avoir les deux pour que ce qu'il y a à comprendre rentre bien dans le crâne du lecteur). Mais sur la partie formelle (c'est à dire en gros les steps) on essaie d'être en anglais, aussi lisible que la partie informelle.
Ce qui a bien changé pour moi depuis cette discussion d'il y a 20 ans, c'est que j'ai réalisé à quel point l'exercice de génération de documentation à partir du code était vain.
Je ne lis jamais ces docs. Déjà à l'époque, tout les IDE (moi j'étais sous emacs) permettaient de sauter directement à la déclaration de la fonction truc, ou se trouvaient les commentaires permettant de générer la doc. Donc la doc ne servaient à rien.
Au contraire, les tags mis dans les commentaires pour effectuer la génération viennent rendre la code moche et moins lisible. C'est pourquoi je faisais l'apologie de NaturalDocs à l'époque (et de Markdown maintenant) : embellir, OK, mais l'original doit rester lisible, tant que ce sera la que l'on travaillera en premier lieu.
La doc la plus intéressante contient justement ce qui ne figure pas dans le code, ce que le code ne peut pas transcrire (cf. le niveau sémantique dont je parlais plus haut). Et, petit parallèle avec literate programming, il n'y a pas forcément d'endroit idéal dans le code pour mettre ces infos en commentaire.
Des choix d'architecture, par exemple, pourquoi les mettres dans un source plutôt qu'un autre? Leurs place n'est en fait pas dans un source, mais dans un doc qui s'appele "choix d'architecture".
je n'utilise plus de header systématique de fichier ou de fonction, qui stimule l'écriture de commentaires à 80% insipide. Si j'ai quelque chose à dire, je le dis. Dans la spec si ça concerne l'utilisateur, dans le body si ça concerne le mainteneur.
Donc, j'essaie :
1. d'écrire un code clair (quel pied quand il n'y a pas besoin de commentaire!)
2. je mets des commentaires là ou il faut, et pas plus.
3. je n'extrait plus rien du code, si tu veux voir le code, ben va voir le code!
Mon code est beau :-), il n'a rien à cacher et n'a pas besoin de maquillage. Ton IDE est génial, tu peux naviguer avec, pas besoin d'html.
4. la documentation qui m'intéresse le plus sur un outil, c'est celle qui m'explique ce que je peux faire avec. Or, et là on rejoint le sujet, cette doc donne généralement des exemples, des limitations et des cas d'erreurs, que l'on retrouve également dans les tests.
Donc, terminé d'écrire deux fois les choses : maintenant, avec bbt, j'écris un seul des deux.
Mais peut-être que dans encore 20 ans je dirai tout autre chose :-)
(Si GPT 13.z me laisse encore programmer).