Introduction

Sur un des projets sur lesquels j’interviens, diverses personnes ont contribué au cours des années parfois sans passation entre les équipes. 

En regardant les commits, on voit qu’une équipe a mis un ORM, une autre l’a enlevé, une autre a mis un autre ORM etc.. 

Le coût en temps pour l’entreprise est considérable car ce n’est pas une opération anodine et surtout on ne sait pas toujours ce qui a motivé cette décision.

Les Architecture Decision Records (ADR) sont une réponse à ce problème: l’objectif est que toutes les décisions d’architectures (ce qui a été adopté ou envisagé) soient connues de toute personne travaillant sur le projet.

Le problème lorsqu’il n’y a pas de continuité d’équipe

Lorsqu’une nouvelle équipe reprend un projet avec peu ou pas de passation de l’équipe précédente, on peut avoir les problèmes suivants:

La nouvelle équipe arrive sur un projet et a de la frustration sur certaines façons de faire ou certains choix. Il y a deux écoles:

Ceux qui se disent “les développeurs d’avant c’était une équipe de peintre” et qui veut tout changer

Les prudents qui se disent “ils devaient avoir une bonne raison” et qui continuent d’appliquer une méthode à laquelle l’équipe ne croit pas

Dans le premier cas, il y a un gros risque:

• On critique ce qui a été fait

• On arrive à convaincre et on commence à implémenter la nouvelle façon plébiscitée

• On se rend compte en plein milieu de l’implémentation des raisons qui avaient poussé à faire la solution d’origine

Le coût moral et financier de cette opération est terrible car c’est dur d’admettre qu’on s’est trompé et de revenir en arrière (surtout après avoir bien critiqué les équipes d’avant !).

Dans le second cas:

Il y a de la frustration également et c’est dur de convaincre les nouveaux arrivants de la façon de faire. On reste prisonnier de l’application alors que la raison de ce choix n’existe potentiellement plus aujourd’hui.

De façon concrète j’ai été dans ce cas où je n’étais pas convaincu du tout par le framework de test utilisé dans un de mes projets. Étant de nature prudente je ne l’ai pas changé pendant 1 an car je me disais qu’il devait y avoir une bonne raison de l’utiliser.

En creusant, je me suis rendu compte qu’en 2016/2017 lors de son introduction, ce framework présentait de nombreux avantages et l’équipe de l’époque avait pu gagner du temps grâce à lui.

Ce framework n’ayant pas connu un gros succès, il s’est fait rattrapé et ne me semblait plus être la meilleure option dans mon contexte.

J’ai donc perdu du temps à apprendre ce framework et passer du temps à faire de l’archéologie sur gitlab et sur internet afin d’être convaincu que mon choix de changer de technologie était pertinent.

Si un de ces exemples vous parle alors la mise en place d’un ADR peut vous permettre de résoudre ces problèmes ! 

Un ADR c’est quoi ?

L’acronyme fait sérieux mais c’est juste un document versionné dans votre projet où vous documentez une décision d’architecture.

La mise en place d’un ADR prend 1h max le temps de se mettre d’accord sur un template avec l’équipe et va permettre de faire gagner un temps considérable au cours du temps !

Vous avez des templates dispo ici: https://github.com/joelparkerhenderson/architecture-decision-record

Exemple:

1. Remplacer Junit par TestNG

Statut
Accepté

Contexte

Les tests unitaires nous semblent long à exécuter et difficile à lire.
Décision
Utiliser TestNG au lieu de Junit
Conséquences

Avantages

On aura à disposition des assertions plus claires
On pourra run nos tests en parallèle et ainsi gagner en temps d'exécution
On pourra grouper nos tests-cases permettant de gagner en lisibilité

Inconvénient
Moins de ressource disponible

Je ne met pas la date dans l’ADR car on l’a avec Git.

Ca peut être aussi simple que ça, d’autres template peuvent être plus adaptés à vos besoin/ à la décision:

Exemple: https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-jeff-tyree-and-art-akerman/index.md

⚠️ Il faut aussi versionner les décisions refusées afin que les équipes suivantes puissent savoir les raisons du refus s’ils se posent les mêmes questions !

Aller plus loin

Des ressources existent pour écrire de bons ADR:

• https://github.com/joelparkerhenderson/architecture-decision-record

• https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html

Des outils sont aussi à disposition:

• https://github.com/adoble/adr-j

• https://github.com/npryce/adr-tools

Conclusion

Un ADR est très simple à mettre en place dans nos projets et peut faire gagner un temps fou tout en réduisant la frustration des équipes. C’est pour ça que je pense qu’il devrait y en avoir dans la majorité nos projets professionnels !