[Devoxx 2016] Documentation vivante

Ecrire de la documentation est souvent un calvaire, en plus d’être très souvent inutile car elle finira tôt ou tard par ne plus être à jour. D’où le sentiment de perdre du temps. La seule documentation véritablement à jour et précise, c’est le code source lui-même, mais il n’est pas toujours trivial pour un non-développeur de comprendre ce que ça fait.

Lors de Devoxx, Cyrille Martraire a fait une présentation intéressante sur la documentation : puisque le code est naturellement à jour et que notre travail de développeur consiste au final à automatiser, autant générer automatiquement la documentation à partir du code source, au-delà de ce qui se fait traditionnellement avec la javadoc, doxygen, etc. C’est ce qu’il appelle la documentation vivante.

Il a commencé par rappeler une des valeurs de l’agilité :

Working software over comprehensive documentation

Puis, il a rappelé que les buts de la documentation étaient notamment de transmettre la connaissance :

• aux autres
• et à la postérité

Et dans certains cas, c’est aussi une question de mise en conformité (notamment sur les projets critiques).

Nous avons donc d’un côté le code, c’est-à-dire une sorte de documentation à jour mais peu lisible, et d’un autre côté, le besoin d’apprendre rapidement sur le projet. Au final, comment transmettre l’information ?

On peut envisager la transmission par l’oral : lorsqu’un nouveau arrive sur un projet ou sur un sujet, la personne qui sait enseigne au nouveau. Ce procédé a ses avantages : une quantité incroyable d’informations circule rapidement, c’est interactif (on peut reprendre des points que l’on n’a pas compris) et c’est à la demande (et c’est socialement plus intéressant que de lire de la doc). Ainsi, on voit aussi l’intérêt de travailler en binôme (ou en groupe). On apprend ainsi beaucoup sur les sujets techniques comme sur les sujets fonctionnels.

Mais nous pouvons aller plus loin dans l’apprentissage du fonctionnel. D’un point de vue métier, nous pouvons apprendre beaucoup par l’event storming, ainsi qu’avec la rencontre des utilisateurs. Cyrille a aussi mis en avant le DDD. En effet, le DDD n’est rien d’autre que mettre du métier dans le code, ce qui, d’un point de vue documentation, est intéressant puisque les concepts et relations du domaine métier se retrouvent plus évidemment dans le code.

Un des gros problèmes de la documentation “traditionnelle” est qu’elle est rarement à jour. Mais dans cette documentation obsolète, certaines parties restent néanmoins très longtemps vraies. Cyrille a donc fait la distinction entre la documentation qui est valide sur le long terme de celle valide temporairement. Pour cette première (qu’il appelle “evergreen document”), un simple wiki suffit. Il faut néanmoins faire très attention à ne pas y introduire d’éléments variants, au risque de retomber dans les travers que l’on connaît.

Pour la documentation à durée de vie limitée, le BDD est parfaitement adapté. En effet, il permet d’associer la description d’un comportement à un test, et donc du code.

Dans une spécification BDD, on a en général deux parties : une première qui contient le contexte et une deuxième qui contient les exemples concrets. A ces deux parties, il a proposé d’ajouter une troisième, qui contient des commentaires ainsi que des tags pour catégoriser la spécification.

Comme la spécification peut évoluer sans le code, on peut utiliser des outils comme Cucumber ou SpecFlow. Ces outils permettent d’associer code et scénarios. On peut aussi compléter ces outils avec Pickles. Pickles récupère les spécifications (sous format Gherkin) et les met en forme, et ce, sous différents formats : page HTML, pdf, excel, .docx, etc. Quand les pages sortent sous forme de pages HTML, on peut alors rechercher les tags présents dans les spécifications. L’autre avantage de Pickles, c’est qu’on peut savoir ce qui, dans les spécifications, est validé par les tests ou pas.

On peut ensuite aller plus loin dans l’intégration des concepts du DDD pour générer de la documentation. Par exemple, il a ajouté des annotations, comme @BoundedContext, dans son code. Lesquelles sont associées avec du texte pour les décrire. Ajouté à un analyseur de code source qui va prendre toutes ces classes annotées, il peut générer de la documentation.

/**
 * Explication sur ce qu’est un BoundedContext, avec un lien vers la page de Martin Fowler (https://martinfowler.com/bliki/BoundedContext.html)
 */
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Target(ElementType.PACKAGE)
public @interface BoundedContext {
String name();
String domain() default “”;
String[] qualityAttributes() default {};
String[] links default {}
}

Et dans le package-info.java (fichier qui contient la documentation d’un module en Java) :

/**
 * Explication du BoundedContext
 */
@BoundedContext(name=”mon contexte, links =”lien vers une page avec plus d'explications.html”)
package fr.foo.bar.domain

import fr.foo.bar.annotations.BoundedContext

En ajoutant des annotations comme @ValueObject, @CoreConcept, dont on peut extraire les propriétés et la javadoc (avec les Doclet, Java annotation processing, etc.), on peut générer un glossaire. Pour ses glossaires par exemple, il prenait la javadoc du package-info.java annoté avec @BoundedContext, l’ajoutait en entête, puis prenait toutes les javadoc de toutes les classes annotées avec @CoreConcept, @ValueObject, puis agrégeait tout ce contenu dans un PDF qu’il pouvait ensuite redistribuer. Ainsi, le langage métier était connu de tous.

Jusqu’à présent, nous avons évoqué la documentation générée à partir du code. Néanmoins, il peut être utile aussi de générer différents diagrammes, d’appels par exemple. Pour les diagrammes faits rapidement sur un coin de table, il a proposé l’utilisation de Diagrammr (inaccessible à ce jour) ou de Graphviz. Le premier permet, à partir de phrases très simples (“applicationA appelle applicationB, applicationB appelle applicationC”) de générer un graphe. Quant au second, si on arrive à transformer un fichier quelconque (xml, autre…) en un fichier .dot, il convertit ce dernier en un joli graphe.

Pour le reste, il a conseillé d’utiliser au maximum les conventions (de nommage, de conception, etc.) : plus il y en a et plus il est facile de s’y retrouver, un peu comme avec Maven. Et donc le besoin de documenter se fait moins sentir. Il a aussi souligné que s’il était difficile de générer de la documentation, c’est probablement parce qu’il y avait un problème de conception ou de propreté du code (et dans ce cas, il vaut donc mieux réécrire un peu le code). Et donc qu’il fallait aussi être à l’écoute des frustrations qui pouvaient être des révélatrices de problèmes. Un moyen de vérifier si les domaines sont bien présents dans le code, c’est de faire un nuage de mots. Ceux qui doivent apparaître le plus sont ceux du domaine métier.

Générer automatiquement la documentation répond donc aux problématiques de la documentation : non seulement ça peut être aussi amusant que de coder, mais en plus, elle est à jour.

Pour aller plus loin, Cyrille Martraire a rédigé un livre, disponible ici.

© SOAT
Toute reproduction interdite sans autorisation de la société SOAT