BT

DDD et la Documentation Vivante

| par Jan Stenberg Suivre 37 Abonnés , traduit par Julien Delhomme Suivre 1 Abonnés le 30 juin 2015. Durée de lecture estimée: 2 minutes |

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.

Evaluer cet article

Pertinence
Style

Bonjour étranger!

Vous devez créer un compte InfoQ ou cliquez sur pour déposer des commentaires. Mais il y a bien d'autres avantages à s'enregistrer.

Tirez le meilleur d'InfoQ

Donnez-nous votre avis

Html autorisé: a,b,br,blockquote,i,li,pre,u,ul,p

M'envoyer un email pour toute réponse à l'un de mes messages dans ce sujet

Quelle différence avec avant? by Erik Gollot

Je comprends pas bien. Living documentation ça me fait gravement penser aux modèles de classes UML (DDD normal...) et les feature ou scénario aux bonnes vieilles règles de gestion et cas d'utilisation avec leurs scénarios.

On jette puis on revient aux fondamentaux, non ?

Html autorisé: a,b,br,blockquote,i,li,pre,u,ul,p

M'envoyer un email pour toute réponse à l'un de mes messages dans ce sujet

Html autorisé: a,b,br,blockquote,i,li,pre,u,ul,p

M'envoyer un email pour toute réponse à l'un de mes messages dans ce sujet

1 Discuter

Se connecter à InfoQ pour interagir sur ce qui vous importe le plus.


Récupérer votre mot de passe

Follow

Suivre vos sujets et éditeurs favoris

Bref aperçu des points saillants de l'industrie et sur le site.

Like

More signal, less noise

Créez votre propre flux en choisissant les sujets que vous souhaitez lire et les éditeurs dont vous désirez suivre les nouvelles.

Notifications

Restez à jour

Paramétrez vos notifications et ne ratez pas le contenu qui vous importe

BT