Specification by example et documentation vivante

Specification by example & documentation vivanteEn 2015,  avec Brice nous avons présenté une session à Agile Grenoble intitulée « Specification by example : venez assister à la naissance d’une documentation vivante ». Depuis nous avons présenté à plusieurs reprises cette session qui est à chaque fois accueillie avec enthousiasme. Elle se compose en 3 parties : présentation de la théorie, un exemple concret interactif et un retour d’expérience. La collaboration étant ag15_logo_speaker_blancau cœur de ce processus, cette méthode implique tous les intervenants d’un projet : analystes métier, développeurs, testeurs et managers.

Des exemples utiles à différentes phases du projet

Comme l’explique le livre de Gojko Adzic, travailler avec des exemples est intéressant lors des différentes phases du projet :

  • Compréhension partagée : en amont du développement, travailler avec des exemples permet de lever des ambiguïtés et de s’assurer que l’on parle bien des mêmes choses. De plus si tous les intervenants sont impliqués à cette phase, cela joue aussi sur la dynamique d’équipe.
  • Acceptance test : dès le début du développement, l’exemple est entré dans l’outil d’automatisation. Il devient un « acceptance test » de la double boucle TDD. Il prend alors un  rôle de pense bête : il reste rouge tout le long du développement et passe vert lorsque le logiciel satisfait toutes les exigences.
  • Regression test: une fois vert l’exemple change encore d’objectif. Il sert maintenant à détecter les régressions. Un bon exemple nous indique dans quelle fonctionnalité s’est glissé le bug.
  • Documentation vivante: un autre aspect est maintenant de jouer un rôle  documentaire de l’application. Cette documentation évolue en même temps que le logiciel et est vérifiée en continu.  Il arrive parfois que l’ajout d’une fonctionnalité rende obsolète certaines contraintes qui avaient été ajoutées précédemment. En passant rouge, les exemples nous indiquent l’impact du changement.

Où se trouve la poule aux œufs d’or ?

8218-FX-6-0-13-6-9-0-90-5-5-95-95Cette méthode n’est pas magique. Son implémentation demande des efforts et un changement culturel. Aussi j’insiste régulièrement sur le fait que cette méthode apporte énormément de valeur sur l’étape de compréhension partagée et de documentation vivante.

A mon sens, il n’y a pas d’autres méthodes qui challengent autant l’expression du besoin et la documentation. Aussi comme trop d’information tue l’information, quand je suis face à des questions sur l’exhaustivité où la qualité des exemples, j’essaye d’identifier à quelle phase profite l’exemple. Si j’investis sur la documentation, l’exemple a certainement de la valeur. Par contre si je rajoute des exemples uniquement pour me protéger de la régression, j’essaye de voir si je ne peux pas les rajouter dans d’autres tests (robustesse, intégration, etc…)

La phase de compréhension partagée porte en elle même beaucoup de valeur. A cette étape c’est le besoin qui est challengé. Les « product owners » doivent illustrer le besoin par des exemples concrets. En ayant des représentants de l’équipe métier, développement et test, l’interaction des différents points de vue va enrichir l’idée initiale.

Dans l’exemple pratique de la présentation, nous tentons d’illustrer l’impact du changement en ajoutant une règle qui est incohérente avec une autre. Sur cette simulation cela semble simpliste, mais nous avons récemment vécu cette illustration :

Nous voulions légèrement modifier un calcul affiché à l’écran. Il était difficile, tant le système était complexe, de détecter que cela rendait obsolète une autre fonctionnalité.

Pour moi l’efficacité de cette méthode est à rapprocher du principe « Mutal Benefit » de eXtrem Programming : une même activité (la rédaction d’un exemple) apporte de la valeur dès l’instant présent. Le principe est d’écrire un exemple parce que cela est utile maintenant pour définir ce que doit faire l’application. Pas uniquement parce qu’un jour il va potentiellement servir. En automatisant la vérification de l’exemple on récupère les fruits de cet investissement tout au long de la vie du projet.

Emblem-question.svgLes questions qui reviennent souvent

Lors de nos diverses présentations certaines questions sont récurrentes. En voici quelques-unes :

  • Vous parlez de pyramide des tests, n’êtes-vous pas en train de faire une pyramide inversés ?
    • Effectivement, le nombre d’exemples augmente avec le temps et le besoin de documentation. Cependant ce n’est qu’une partie des tests. Nous nous en servons comme test d’acceptance et de nombreux tests unitaires sont écrits en même temps que le code. Notez que cette documentation est très utile pour les testeurs pendant les recettes lors des phases de livraison.
  • Est-ce que l’approche est similaire à celle du TDD ? C’est-à-dire que si on n’arrive pas à tester c’est qu’il y a un problème de design ?
    • Par le fait d’automatiser des exemples, il y a forcément une influence sur le design. Cependant ce n’est pas son objectif, le besoin est beaucoup plus chahuté par cette approche. Si le besoin n’est pas très clair, on a une opportunité de s’en rendre compte dès la phase de compréhension partagée. A ce stade le changement coûte moins cher.
  • A propos de l’impact au changement, n’y a-t-il pas moyen de l’identifier avant le développement ?
    • Effectivement si une incohérence n’a pas été levée lors de la 1ère phase, ce n’est que lorsque le code va être modifié que l’on va savoir quel est l’impact du changement. Cependant comme cette incohérence est connue, cela permet de statuer et de mettre à jour la documentation. On a alors une nouvelle source de vérité sur ce que fait l’application (l’autre étant le code).
  • Quel est le coût pour la mise en place de cette méthode ?
    • Ce n’est pas facile de répondre à cette question quantitativement. Cela dépend de l’organisation mise en place. Sur notre projet, les développeurs ont pris en charge une bonne partie (~20-30% temps de développement). Cependant tout le monde s’accorde pour dire que cela vaut le coup : l’application a peu de bug, il y a moins d’incompréhension. C’est aussi l’unique documentation utilisée par le métier, les développeurs et les testeurs.

J’espère vous avoir donné envie de tenter l’aventure Specification by example. La présentation est disponible sous SlideShare et le code sous GitHub.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *