Petit test de Documentation Driven Development

une ampoule en noir et blanc

Il y a quelques jours, alors que je bossais sur mon pet project du moment, je me suis surpris à penser « tiens, ça serait bien si cette fonctionnalité devenait une application Django réutilisable ». La fonctionnalité en question ne nécessitant pas plus de quelques lignes, je me suis dit que ce serait rapidement torché.

Le fait que je me retrouve 10 jours plus tard et deux applications supplémentaires me prouve encore une fois que je suis vraiment mauvais avec les estimations. Et on s'étonne que je ne travaille pas au forfait

Quoi qu'il en soit, pour la dernière app, j'ai décidé de tester l'approche Documentation Driven Development. Retours d'expérience.

TDD, DocDD, Quésaco ?

Les lecteurs de Miximum étant tous belles / beaux et intelligent·e·s, je ne vous apprendrai pas ce qu'est le TDD, ou Test Driven Development, qui consiste à écrire les tests avant d'implémenter une fonctionnalité donnée. Pour la beauté de la démonstration, je rappelle quand même le fonctionnement basique, juste au cas où :

  1. déterminer la fonctionnalité à écrire ;
  2. écrire le test ;
  3. lancer le test pour le faire échouer ;
  4. écrire le code minimal pour faire passer le test ;
  5. lancer le test pour le faire passer ;
  6. refactoriser si besoin ;
  7. vérifier que le test passe toujours ;
  8. aller prendre un café ;
  9. itérer.

Je n'aurai pas non plus l'outrecuidance de vous rappeler les énormes avantages de cette façon de travailler :

  1. on réfléchit avant de démarrer l'implémentation ;
  2. on est obligé d'écrire du code testable ;
  3. on obtient une meilleure couverture de tests, du code de meilleure qualité et plus facilement maintenable ;
  4. on a donc plus de temps pour boire du café (ce qui je le rappelle est la raison de vivre de tout développeur·s·e qui se respecte.

Et le Document Driven Development, ou DocDD (parce que DDD est déjà pris) ?

Contrairement au TDD qui est une vénérable pratique ayant sa place dans tout manuel du bon développeur, le DocDD n'est à ma connaissance pas vraiment formalisé, et reste cantonné à quelques expérimentations relatées dans deux ou trois billets poussiéreux traînant dans un recoin du Web.

Le principe est pourtant séduisant : écrire la documentation avant d'écrire le code.

L'approche DocDD

L'approche DocDD est relativement simple :

  1. déterminer la liste des fonctionnalités à fournir ;
  2. écrire la doc complète ;
  3. écrire le code qui fait marcher la doc ;
  4. vérifier que la doc est bien respectée ;
  5. aller prendre un café ;
  6. itérer.

DocDD partage quelques similarités avec TDD. En effet, il peut sembler contre-intuitif pour le néophyte d'écrire de la doc et / ou des tests pour du code qui n'existe pas encore. Pourtant, les deux pratiques nous amènent à réfléchir avant de coder, ce qui ne peut qu'être positif.

Mais là ou TDD est une pratique assez « bas niveau », près du code, DocDD nous pousse à prendre de la hauteur et contempler notre application dans son ensemble, comme le ferait un utilisateur final ou un développeur fraîchement débarqué sur le projet. On s'interroge sur le « quoi » plutôt que sur le « comment ».

Là ou TDD amène à une meilleure qualité technique du code, DocDD amène à une meilleure cohérence de l'API dans son ensemble, et donc une meilleure utilisabilité du produit final par des humains.

DocDD me semble donc tout tout particulièrement indiqué pour les projets à vocation réutilisable, notamment les bibliothèques open-source, les applications Django, etc.

DocDD et agilité

Une bite de trottoir souriante

« Un logiciel fonctionnel plutôt qu'une documentation complète » nous dit le manifeste agile. DocDD superfétatoire (mot compte triple) ? Ma réponse : ça dépend.

Dans le cadre de certains projets de développement, une documentation complète n'est pas vitale. Dans le cadres de bibliothèques, apis, applications réutilisables, etc. en revanche, la documentation fait partie du produit.

Si « la fonctionnalité doit être documentée » se trouve quelque part dans votre DoD, alors écrire la doc au préalable reste le moyen d'être certain qu'elle ne sera pas oubliée à cause d'un coup de bourre et / ou de flemme.

DocDD et itérations

En TDD, on itère. Et en DocDD, alors ? On peut, mais sur des intervalles de temps plus long. Doit on imaginer une phase d'écriture de doc par story ? Sprint ? Release ? Je ne sais pas.

DocDD et MVP

Ceux qui ont tenté l'expérience le confirmeront : délimiter un MVP en déterminant un jeu de features suffisamment réduit tout en restant cohérent est une tâche difficile.

Écrire la doc peut-être un moyen assez intéressant d'y parvenir. C'est l'approche que j'ai testé en documentant django-simple-sms.

Devant un tableau blanc, il m'est difficile d'avoir une vision claire des choses, mais en tant que développeur, j'arrive assez bien à me dire « si je devais utiliser ce produit, quelle documentation aimerais-je trouver ? ».

DocDD comme un outil de spécification

Même si les mordus d'agilité ont compris qu'écrire un gros cahier de spécification en début de projet est une perte de temps, ça n'empêche pas le besoin d'échanges entre le Product Owner et l'équipe. Écrire de la doc peut-il être un bon moyen d'échanger sur les spécifications d'une fonctionnalité ? Je ne sais pas, mais j'ai l'impression qu'il y a quelque chose à creuser.

Vade Retro Bisounours !

Ce billet étant issu d'une simple expérimentation personnelle sur un projet de très faible envergure, il me reste pas mal de questions en suspens :

  • comment réagir face aux difficultés d'implémentation une fois l'API déterminée ?
  • qu'en est-il des risques de duplication d'information (autodoc) ?
  • qu'en est-il des risques d'obsolescence de la documentation dans le temps ?
  • est-ce que mon code Python ne va pas finir par ressembler à du Java ?

Par ailleurs, cette approche est forcément limitée. D'abord, une bonne doc est destinée à des humains, pas des machines. Il n'est donc pas possible de « tester » une documentation de manière automatique.

De plus, là où TDD met en œuvre des dizaines de micro-itérations chaque jours, DocDD opère plutôt sur des cycles de plusieurs jours. Cette démarche est-elle suffisamment agile ?

En résumé

Je me suis bien amusé à écrire la doc d'une appli Django avant la moindre ligne de code. J'ai trouvé l'approche intéressante et ai l'impression que le résultat final sera meilleur que si j'avais procédé dans l'ordre inverse. Je me demande dans quelle mesure cette pratique peut-être applicable dans d'autres contextes.

Sur ces bonnes questions, je vous laisse, je vais reprendre un café.