Faire de la documentation, c'est ennuyeux. Elle est souvent obsolète et sujette à mauvaise interprétation. Pourtant, il est possible d'adopter un état d'esprit différent qui vous permettra d'améliorer votre documentation comme votre code. C'est ce qu'a démontré Cyrille Martraire lors de sa présentation à la conférence DDD Exchange de cette année à Londres, en nous montrant comment créer une documentation vivante lorsque l'on travaille avec Domain Driven Design.
Pour Cyrille, la documentation à pour but principal de transmettre la connaissance, aux autres, mais aussi pour le futur. Et dans certains cas, celle-ci est même parfois nécessaire pour des raisons de conformité. DDD s'intéresse à la connaissance du domaine métier et une des façons de capturer cette connaissance est de pratiquer l'Event Storming. Pour Cyrille, il s'agit d'une bonne façon de découvrir le domaine. Pour documenter les comportements, il recommande BDD, Behaviour Driven Development, qui permet de les formaliser sous forme de scénarios en utilisant des conversations et des exemples concrets. C'est un premier exemple de documentation vivante, toujours synchronisée avec le code, puisqu'avec des outils comme Cucumber, les scénarios peuvent être exécutés en utilisant le code réel.
Lorsque l'on examine le code dans la perspective de DDD, on retrouve les Bounded Contexts du domaine, bien qu'ils soient souvent matérialisés de façon implicite. Cyrille conseille d'annoter les packages et les namespaces pour ajouter des déclarations et des descriptions des différents contextes, éléments de documentation se trouvant encore une fois synchronisés avec le code. Avec cette technique, on peut en profiter pour décrire différents concepts de DDD. Pour Cyrille, ceci constitue un bénéfice supplémentaire de grande valeur, qu'il qualifie "d'apprentissage embarqué".
De la même façon, le langage ubiquitaire est déjà présent dans le code, dans les classes, les interfaces, les méthodes. En annotant les parties correspondantes au domaine et en mettant en place un mécanisme d'analyse du code, il crée un glossaire vivant, généré automatiquement et toujours à jour. Cyrille a expérimenté avec succès cette technique lors d'anciens projets en partageant systématiquement ce genre de glossaire avec les responsables du projet.
Concernant la conception et sa documentation, Cyrille prend l'exemple de l'architecture hexagonale qui place le modèle du domaine au centre et le reste à l'extérieur. Appliquer soigneusement ce pattern, qui se trouve lui-même être déjà documenté, au code lui permet de s'assurer que la conception se retrouve dans le code et, en utilisant ici encore des annotations sur les packages et les namespaces, il est possible de créer des diagrammes conformes au code.
Cyrille mentionne un autre avantage important de ces techniques : si vous trouvez difficile de créer un glossaire ou d'autres formes de documentation vivante, cela pourrait être le signe d'une mauvaise mise en pratique de DDD. C'est une confrontation du code avec la réalité et une façon de l'améliorer en s'appuyant sur la documentation.
Cyrille Martraire est actuellement en train d'écrire un livre, Living Documentation, disponible sur LeanPub. Le DDD Exchange de l'année prochaine est prévu le 10 juin 2016 et les inscriptions sont ouvertes.