Pourquoi il faut écrire des ADR

ADR = Architecture Decision Records

Consigner dans la base de code pourquoi des décisions d’architecture ont été prises de cette manière.
GitHub l’applique dans ses équipes mobiles iOS/Android, et cet article explique pourquoi c’est nécessaire.

Ce n’est pas pour vous, c’est pour votre vous du futur

Un ADR n’est pas un exercice de réflexion sur une décision que vous avez prise : il aide à se souvenir de l’état d’esprit dans lequel cette architecture a été décidée, 6 à 12 mois plus tard.
Un ADR capture le moment où la décision est prise, et inclut jusqu’aux PoC abordés en réunion, en visio, sur Slack ou dans le code.
L’idée est de faire sortir ce contexte de votre tête pour le formuler, afin de pouvoir le remettre en tête plus tard lorsque vous réexaminerez cette architecture.

Le vrai bonus apparaît quand, quelques mois plus tard, quelqu’un vous demande d’un ton accusateur pourquoi le module GitHubAPIClient fonctionne de cette manière.
Au lieu de passer 30 minutes en pair programming à expliquer le code, vous pouvez lui donner cet ADR, qui permet d’expliquer les décisions prises pendant la construction de ce module.

Ce n’est pas pour vous, c’est pour vos collègues

Un ADR doit aller plus loin qu’une simple ligne du type « cette fonctionnalité implémente la feature #3128 ».
C’est une forme d’explication plus développée qui aide vos collègues à comprendre pourquoi cette fonctionnalité a été conçue ainsi plutôt qu’autrement.
(Par exemple avec des sections comme « alternatives envisagées » ou « avantages et inconvénients » dans l’ADR.)

Ce qui vous paraît simple peut être complexe pour vos collègues.
Prendre un peu de temps pour noter le raisonnement qui vous a conduit à une décision donne aux membres de l’équipe une occasion d’entrer dans votre tête.
Rédiger un ADR permet la « socialisation des décisions ».
Cela aide l’équipe à prendre des décisions dont elle assume collectivement la maintenance, au lieu de décisions prises de manière isolée.

Si vous rédigez un ADR avant d’ouvrir une pull request, vous pouvez obtenir de meilleures revues de PR de la part de l’équipe qui l’examine.

Ce n’est pas pour vous, c’est pour vos futurs collègues

Un ADR n’a pas pour but de montrer à quel point vous êtes intelligent, ni de laisser les gens perplexes face à l’architecture que vous avez conçue.
Un ADR aide les nouveaux membres de l’équipe à comprendre la base de code actuelle et la manière dont elle a évolué au fil du temps.

À mesure que l’équipe s’agrandit et se développe, les canaux de communication entre ses membres se multiplient.
Mettre par écrit les décisions prises aide aussi à communiquer avec les personnes qui rejoignent l’équipe à mesure qu’elle grandit.

Le meilleur scénario, c’est qu’un membre de votre équipe écrive un nouvel ADR qui remplace une décision que vous aviez prise auparavant, et qu’à l’avenir vous puissiez apprendre de vos collègues.

« Écrivez davantage d’ADR. À mesure que notre équipe grandit et que la base de code devient plus complexe, les ADR sont un excellent moyen d’aider notre nous du futur, les membres actuels de l’équipe et les futurs membres de l’équipe. »

[xguru]

Parmi les cas d’administration électronique, le très connu Gov.UK dispose également d’un repository où sont regroupés ses ADR liés à son architecture cloud sur AWS.

https://github.com/alphagov/govuk-aws/…

[beatblue]

C’était une bonne référence.

[xguru]

Exemples d’ADR

Décision sur le framework CSS

https://github.com/joelparkerhenderson/architecture_decision_record/…

• Problème : il faut choisir un framework CSS pour une webapp. Il doit être rapide et stable, quel que soit le navigateur courant ou la taille d’écran. Il faut permettre des itérations rapides sur le design, la mise en page et l’UI/UX. Design responsive

• Décision : décision d’utiliser Bulma

• Hypothèse : comme nous voulons créer une webapp moderne, rapide et responsive, nous ne voulons pas utiliser jQuery

• Contrainte : un framework qui peut être utilisé sans jQuery

• Options envisagées : ne rien utiliser, ou choisir entre Bootstrap/Bulma/Foundation/Materialize/Semantic UI, avec une réflexion approfondie sur Bulma et Semantic UI

Monorepo vs Multirepo

https://github.com/joelparkerhenderson/architecture_decision_record/…

• Problème : notre projet comporte trois catégories principales — UI frontend, middleware et serveur backend

→ nous utilisons git comme SCM, il faut donc trancher entre monorepo vs polyrepo vs hybride

• Décision :

→ Monorepo lorsque l’organisation/l’équipe/le projet est petit et fonctionne en itérations rapides

→ Polyrepo lorsque l’organisation/l’équipe/le projet est grand et que la stabilité est prioritaire

• Hypothèse : le code que nous produisons est destiné à l’organisation et non à l’extérieur (au public)

Décision sur le langage de programmation

https://github.com/joelparkerhenderson/architecture_decision_record/…

• Problème : il faut choisir un langage pour le développement logiciel, pour le frontend web et le backend

• Décision :

→ frontend : TypeScript

→ backend : Rust

• Hypothèses :

→ le frontend doit rester courant, mais permettre un développement, un déploiement et des itérations rapides. Aucune compatibilité legacy n’est nécessaire

→ le backend doit viser un niveau légèrement supérieur au standard. Prise en compte de la qualité, de la stabilité et de la sécurité. Un niveau quasi temps réel est requis (il ne doit pas y avoir d’arrêt dû au GC). La programmation fonctionnelle / le traitement parallèle et le multicœur, ainsi que la sûreté mémoire, sont aussi importants

• Limitation : il doit absolument pouvoir s’exécuter dans le serverless des grands services cloud (Amazon Lamba)

• Options envisagées : C/C++/Clojure/Elixir/Erlang/Elm/Flow/Go/Haskell/Java/Javascript/Kotlin/Python/Ruby/Rust/TypeScript

• Débat :

→ C : exclu pour sa faible sûreté ; Rust peut mieux faire la plupart des choses

→ C++ : exclu car trop désordonné ; Rust peut mieux faire la plupart des choses

→ Clojure : excellente modélisation ; le plus proche de Lisp ; excellent runtime sur la JVM

→ Elixir : excellent runtime pour le déploiement et la concurrence ; excellente expérience développeur ; écosystème relativement réduit

→ Erlang : excellent runtime pour le déploiement et la concurrence ; expérience développeur assez exigeante ; écosystème relativement réduit

→ Elm : prometteur ; IBM partage de bons cas d’usage ; petit écosystème

→ Flow : amélioration intéressante de JS ; mais les développeurs s’en éloignent

→ Go : excellente expérience développeur ; excellente concurrence ; certaines mauvaises décisions ont rendu le langage étrange

→ Haskell : meilleur langage fonctionnel ; petite communauté de développeurs ; peu de réussites en production

→ Java : meilleur runtime ; excellent écosystème ; expérience développeur moyenne

→ JavaScript : langage le plus populaire ; écosystème le plus vaste

→ Kotlin : améliore de nombreux aspects de Java ; excellent soutien de JetBrains ; divers exemples de réussite de passage de Java à Kotlin

→ Python : langage le plus populaire pour l’administration système ; bons outils d’analyse ; bons frameworks web ; abandonné quand Google a choisi Go

→ Ruby : meilleure expérience développeur ; meilleur framework web ; excellente communauté ; extrêmement lent ; difficile à packager

→ Rust : meilleur nouveau langage ; met l’accent sur les Zero-cost abstractions (pas de perte de vitesse malgré l’abstraction) ; accent sur la concurrence ; écosystème relativement réduit ; quelques limites dans certaines optimisations du compilateur (par exemple l’accès direct à la mémoire doit être unsafe)

→ TypeScript: ajoute des types à JavaScript ; excellent transpiler ; les développeurs migrent progressivement de JS vers TS ; fort soutien de Microsoft

• Décision de ne pas choisir une base VM (car cela augmente la complexité)

• Pour le runtime le plus rapide, choisir JS et C

• Pour un runtime presque aussi rapide que le meilleur, choisir TypeScript et Rust

• Si une VM et un framework web avaient été choisis

→ Closer et Luminous

→ Java et Spring

→ Elixir et Phoenix