SAW – post-mortem

Hier, j’ai publié la version 1.0.0 de SAW.

La branche master est donc maintenant décorée d’un joli petit tag 1.0.0, et la documentation est à jour. Joie, bonheur, et allégresse ! Ce n’est pas grand chose, d’abord et surtout parce que personne ne l’utilise à part moi, ce qui fait que je n’ai pas de problèmes à résoudre, pas de bugs bizarres que je n’arrive pas à reproduire chez moi… Mais pour autant, la publier n’était pas vide de sens.

« Release early, release often »

D’une part, avant tout, la publier est bon moyen de “tourner la page” : elle est disponible, elle a un tag 1.0.0, elle est publiquement accessible, son backlog est vide, c’est ça de charge cognitive en moins. Et, malgré ma tendance à avoir au moins une nouvelle idée de projet par jour, c’est le premier sur lequel je bosse seul que j’estime vraiment publiable… C’est aussi que je suis très perfectionniste au sujet du code que j’écris ; publier un projet, c’est commencer à accepter qu’il ne sera jamais parfait, c’est rejeter ma “timidité” et intégrer l’idée que ce sont les critiques et les retours qui permettent d’avancer et de l’améliorer.

Pour autant, j’ai bien conscience de me mentir à moi-même : l’idée derrière ce principe consistant à publier vite et souvent est de ne pas attendre d’avoir trop avancé dans une direction pour demander des retours, des avis, alors que je suis en train de publier, lentement, projet après projet, du code “parfait” dont je n’ai plus envie de m’occuper… Mais j’ai commencé l’année avec la résolution de me libérer l’esprit de tous mes projets en cours : tout finir, tout documenter, tout tester, écrire de long messages de publication introspectifs qui ne sont qu’une excuse pour caser de vieux memes… et tout ça c’est, quelque part, malgré tout, en un sens, je pense, un pas dans la bonne direction.

C’est quoi une “documentation” ?

Ce qui m’amène (de manière détournée) vers le principal sujet que je voulais aborder : l’écriture de la documentation. C’est une question difficile, au sujet de laquelle beaucoup a déjà été dit. Mais en écrivant la documentation de SAW j’ai compris quelques notions qu’il me fallait expérimenter par moi-même.

Et donc, qu’est-ce qu’une “documentation” ? Vous savez ce… truc qui va avec le code et qui… explique le code ? Je crois ? Le terme “documentation” est vague et peut désigner plusieurs choses différentes. La première chose que j’ai réalisée : à qui s’adresse cette documentation ? Pour quelle raison ai-je besoin de l’écrire ?

Hé bien, SAW est une bibliothèque. Son but est d’être utilisée par d’autres développeurs qui veulent en utiliser les fonctionnalités. La documentation s’adresse donc à “des développeurs”. Mais là encore le terme est vague : pour être précis elle s’adresse aux développeurs qui veulent l’utiliser, pas à d’hypothétiques développeurs voulant y contribuer. Ce qui me permet d’identifier le but de cette documentation : expliquer l’API publique de SAW.

Le code ne suffit pas

Pendant longtemps j’ai défendu l’idée qu’un code propre était sa propre documentation. Qu’un code pas lisible dont on ne peut pas déduire facilement le but était un code mal écrit, et qu’il fallait le corriger. La documentation, dans cette logique, n’avait qu’un but : expliquer et clarifier les grandes lignes du design et de l’architecture. Le code se charge d’expliciter les détails. Je m’insurgeais du coup contre l’abus de commentaires verbeux dans le code, surchargeant un beau fichier tout propre d’une insipide logorrhée.

//! Creates / open the database in given file
/*!
\param filename: the database file name
*/
void connect(std::string filename);

Aujourd’hui encore je pense que le fichier de code idéal est petit, lisible, et pas encombré par des commentaires. Toutefois, j’ai fini par comprendre qu’il existait tout un ensemble d’éléments, plus précis que les détails d’architecture, plus globaux que les noms des fonction, qu’il était important de documenter :

• cette méthode a une complexité estimée de O(n);
• cette méthode est thread-safe;
• cette méthode a tel ou tel effet de bord.

Bien sûr, plus le langage utilisé est strict, plus il force à expliciter ce genre d’informations. Mais en l’occurrence, SAW est codée en C++, qui est un peu trop permissif…

Décorrélation

Au final, la documentation de SAW n’est pas grand chose de plus qu’une liste des classes et méthodes publiquement accessibles, à peine annotées et expliquées, accompagnées d’un tutoriel qui vise à, lui, présenter un peu le schéma global. Elle souffre (en plus d’être courte et imprécise) du défaut majeur de toute documentation écrite à la main (par opposition à une documentation générée) : le moindre changement dans la base de code doit y être répliqué à la main, car rien n’est pire qu’une documentation erronée.

Ce qui fait que je conclue sur une contradiction : je ne veux pas polluer mon code de commentaires verbeux, mais je n’ai pas envie de devoir faire la synchronisation de la documentation à la main… Il n’y a pas vraiment de bonne réponse. C’est le prix que nous fait payer cette représentation textuelle du code, je suppose.

“Source code in files. How quaint.”
Attribué à Kent Beck

Mais bon, bref, voilà. SAW n’est pas une bibliothèque parfaite, mais elle est enfin disponible. Yay, un projet publié ! Plus que… quelques autres.