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'Architecture Decision Record (ADR) 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. Et bien sûr 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 .

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

L'intérêt de procéder de la sorte est de ne pas rouvrir ces sujets tous les quatre 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.

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 travaille à 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 si vous avez pensé "Event Sourcing", bravo 👏 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. Et cela s'est déjà vu : je connais au moins un cas d'application dans les ressources humaines, sans aucun lien avec la tech.