Architecture Decision Record

Documenter ou ne pas documenter ? Que documenter ? Pour qui ? Ces questions sont à l'origine de débats enflammés au sein des équipes agiles. Courage, fuyons et n'abordons ici qu'un aspect très précis de la question : un aspect qui, à ma connaissance, fait plutôt consensus.

L'ADR (Architecture Decision Record) a pour vocation de documenter les décisions relatives à l'architecture d'un produit, en détaillant les tenants et aboutissants de ces décisions : éléments de contexte, incertitudes et hypothèses faites en conséquence, puis bien sûr les différentes options à l'étude avec leurs avantages et inconvénients. Sans oublier la décision finale. L'objectif est de ne prendre aucune décision structurante à la légère, sur base d'intuitions non étayées ou de préférences personnelles. On ne connaît que trop l'attrait des développeurs pour la dernière architecture ou techno à la mode, forcément "hyper puissante" et que l'on traînera ensuite pendant des années comme un boulet : bonjour ES/CQRS, bonjour les microservices etc.

L'intérêt de procéder de la sorte est de ne pas rouvrir ces sujets tous les 4 matins, à la faveur d'un nouvel arrivant dans l'équipe ou parce que l'on est confronté aux inconvénients propres à l'option retenue. Une décision n'est jamais sans inconvénient, simplement ces inconvénients sont connus et acceptés parce qu'ils vont de pair avec de plus grands bénéfices. Tout cela a été mis dans la balance et pesé une fois pour toutes, de sorte que si les tenants ne changent pas, la décision n'a aucune raison d'être remise en question ; en revanche, si une hypothèse est invalidée par l'expérience, ou si le contexte change, la décision peut être remise à l'étude.

Quelques exemples de sujets que l'on gagnera à documenter au sein d'un ADR :

• Choix d'un pattern de communication entre contextes : orchestration vs. chorégraphie (EDA : Event-Driven Architecture) ;
• Choix d'un mode de déploiement : monolithe modulaire vs. microservices ;
• Choix d'une architecture CRUD vs. architecture hexagonale vs. functional core/imperative shell ;
• Choix d'une stratégie de tests.

Faire la démarche de consigner ces décisions dans un ADR incite également à statuer sur un plus grand nombre de sujets, évitant que chaque développeur code à sa sauce dans son coin. Idéalement, on souhaiterait ne pas pouvoir dire si un bout de code a été écrit par Paul ou par Paulette. La codebase y gagne en homogénéité, ce qui facilite les refactorings ultérieurs. Pour cette raison, mieux vaut souvent une décision dont on sait qu'elle n'est pas idéale plutôt que pas de décision.

Mais au fait, à quel moment doit-on initialiser un ADR ? La création d'un Walking Skeleton est tout indiquée pour cela, puisqu'à cette occasion l'équipe définit les éléments les plus saillants de l'architecture ; ce jalon permet à l'équipe de traverser la phase de développement intense qui mène au MVP en limitant la dette technique. Bien sûr, les choses ne sont pas figées dans le marbre : l'architecture est appelée à vivre au rythme du produit.

L'ADR permet justement cela, mais il faut en préciser la manière : un ADR est immuable. Pour amender une ancienne décision, l'équipe ne modifie pas la décision correspondante : elle en ajoute une nouvelle, qui fait référence à l'ancienne. Autrement dit, un fonctionnement "append only", et vous avez pensé "Event Sourcing" à juste titre 👏 Idéalement, les décisions seront numérotées de manière continue, comme cela se fait pour les factures. Et tout cela sera tracé par un outil de Version Control (communément Git).

À bien y regarder, le fait de tenir un ADR est une pratique très fédératrice pour une équipe, en ce sens que l'acception de son mode de fonctionnement vaut constitution, quand les décisions qui y sont consignées sont autant de lois. Il ne serait d'ailleurs pas aberrant d'en élargir la portée en y faisant figurer des décisions de toutes natures relatives à la vie de l'équipe. Je connais justement le cas d'une certaine #Elodie, qui a importé cette pratique au sein de son équipe RH 👌