Développer par la Documentation

J’ai donc réussi, après approximativement six mois sans avoir touché à mon code, à reprendre pied et à avancer sur DiaVN, qui approche de la première version qui sera capable de prendre en entrée un diagramme Dia, et de produire en sortie un bout de code RenPY.

Le plus difficile a été de reprendre le travail qui avait été laissé en suspens. Après six mois sans avoir touché au projet, inutile de dire que j’ai eu du mal à comprendre ce que j’avais fait, d’une part, mais aussi pourquoi je l’avais fait, et c’est à ce moment-là que je me suis aperçu de l’importance de documenter mon travail - non pas que je ne l’avais pas fait jusqu’à présent, mais je ne l’avais pas suffisamment fait dans l’optique de travailler par bribes, par séquences décousues, au fil de mes rares disponibilités.

Qu’est-ce qui me manquait exactement ?

• d’une part, une documentation non technique, à savoir sur l’architecture du logiciel ainsi que sur les spécificités de la "syntaxe" des diagrammes qui seraient amenés à être l’entrée de DiaVN,
• d’autre part, une liste précise des questions en suspens, des choses encore à faire, avec leur état (à réfléchir, à tester, à programmer).

Comme mon projet n’est pas encore sur github (je ne l’y mettrai que quand ce sera la première version publique), je n’avais pas non plus la possibilité de me faire des todo listes autrement qu’en laissant des commentaires dans le code et en espérant que le code ferait suffisamment sens, six mois après, pour les retrouver et les comprendre.

Donc, pour remettre le pied à l’étrier et la main à la pâte, dans une sorte de métaphore culinaro-hippique de haut vol (au vent), je me suis dit que j’allais faire la documentation en utilisant Sphinx, un outil permettant d’organiser un travail de documentation autour de projets informatiques.

J’ai donc entièrement retravaillé la documentation, en commençant par la partie "non technique", puis en plongeant dans ma documentation technique pour la modifier et l’améliorer. J’ai profité du plug-in "sphinx.ext.todo" pour regrouper sur une seule page toutes les notes de choses à faire éparpillées au sein du code. Ainsi, j’ai ma propre liste avec des liens qui me permettent de savoir quoi aller modifier et quoi faire.

Chemin faisant, je me suis aperçu que faire du développement par les tests (Test-Driven Development ou TDD) c’est bien joli, mais en réalité, la première étape du travail, c’est d’abord d’écrire en langage naturel ce qu’on a envie de faire, bref, de faire de la documentation. J’en suis donc venu à me dire que j’allais mettre en place une forme de "développement par la documentation" de mon projet, à savoir que j’écrirai à présent d’abord ce que je veux faire (avec des bons vieux mots), ensuite j’écrirai les tests qui me permettent de vérifier les scénarios qui correspondent à ce que je veux faire, et enfin j’écrirai le code qui valide les tests et qui par conséquent valide le tout.

Il se trouve que le "Documentation-Driven Development" c’est un vrai truc, même si c’est pas très connu, il y a quelques sites qui en parlent (par exemple cet article intéressant ici). Mais en creusant un peu la question, j’ai découvert qu’il y avait encore un autre concept plus cool, qui s’appelle "programmation littéraire" (en fait en anglais c’est "literate programming", qui n’a pas exactement le même sens, mais qui est intraduisible en français). Ce concept imaginé par un des fondateurs de l’informatique moderne, Donald Knuth (le professeur de Stanford qui publie "The Art of Computer Programming"), est assez génial, dans le sens où le code n’est plus séparé de la documentation (par exemple dans mon cas où il y a d’un côté la documentation non-technique, qui n’est pas dans le code, et de l’autre la documentation technique, qui est intégrée au code), mais mélangé à celle-ci. Ainsi, on écrit son code comme on écrirait un roman, en alternant des phases de description (qu’est-ce qu’on veut faire) et des snippets d’implémentation (on pourrait faire ça comme ça...), et un outil dédié se charge d’extraire le code de la documentation pour générer le projet qui sera amené à être compilé.

Ainsi mélangés, toute modification du code s’accompagne naturellement d’une modification de la documentation attenante. Et je me suis rendu compte que cette idée fonctionne assez bien avec mon flux de travail (workflow) où j’ai tendance à écrire mes idées en langage naturel en milieu de code au fur et à mesure, ce que j’ai fait à l’aide de la todo liste dans mon projet qui est extraite directement du code.

Il était malheureusement trop tard pour basculer sur du literate programming quand j’ai appris l’existence de ce concept car je venais de refaire toute ma documentation et j’étais revenu à un point de familiarité avec mon projet qui fait que je peux avancer sur celui-ci de nouveau, et l’objectif c’est quand même d’arriver à le finir et non de le réécrire X fois. Mais je me dis que j’aimerais bien mettre en pratique ce concept sur un prochain projet... Et faire de la programmation plus littéraire...