Technical Tutorials

L'architecture logicielle consiste rarement à trouver une seule réponse « correcte ». C'est une série de compromis pris sous contraintes spécifiques, dictés par le contexte de l'époque. Pourtant, trop souvent, lorsqu'une équipe migre vers une nouvelle technologie de base de données ou refactorise un monolithe, la raison derrière ce choix s'évapore dans les airs. Des mois plus tard, les nouveaux développeurs regardent le code legacy et se demandent : « Pourquoi avons-nous choisi MongoDB plutôt que PostgreSQL ? »

C'est là que les Architectural Decision Records (ADRs) entrent en jeu. Un ADR est un document qui capture une décision architecturale importante, accompagnée de son contexte et de ses conséquences. Il sert d'histoire de l'évolution de votre logiciel, fournissant aux futurs mainteneurs le pourquoi, et pas seulement le quoi.

Pourquoi les ADRs sont importants

Sans documentation, la connaissance architecturale devient tribale. Elle réside dans l'esprit des ingénieurs seniors qui peuvent quitter l'entreprise. Les ADRs démocratisent cette connaissance. Ils permettent aux équipes de :

Suivre l'évolution de la conception : Comprendre comment le système a changé au fil du temps.
Réduire la fatigue décisionnelle : Se référer aux décisions passées pour éviter de réouvrir des questions déjà tranchées.
Améliorer l'intégration : Les nouveaux membres de l'équipe peuvent comprendre rapidement la dette technique et le contexte historique.
Faciliter de meilleures revues : Les pairs peuvent questionner les décisions sur la base du contexte plutôt que de préférences personnelles.

Le format standard d'un ADR

Bien que les formats puissent varier, l'approche popularisée par Michael Nygard et ADR.org offre une structure robuste. Un bon ADR devrait inclure :

Titre : Un identifiant unique et concis (par ex., 001-utiliser-postgres).
Statut : Proposé, Accepté, Déprécié ou Supersédé.
Contexte : Les forces motrices en jeu, y compris les contraintes techniques, organisationnelles ou réglementaires.
Décision : Le changement ou le choix réel effectué.
Conséquences : Les compromis résultants, tant positifs que négatifs.

Mise en œuvre pratique

Le meilleur endroit pour stocker les ADRs est aux côtés de votre code source, généralement dans un répertoire nommé docs/adr. Cela garantit que la documentation est versionnée avec le code, empêchant ainsi le décalage de la documentation.

Voici un modèle pour créer un ADR en utilisant Markdown :

## 002-adopter-event-sourcing

**Statut** : Accepté
**Date** : 2023-10-27

### Contexte
Notre architecture actuelle basée sur CRUD peine à répondre aux exigences d'audit et à la cohérence des données entre les microservices. Nous avons besoin d'un moyen de suivre chaque modification de l'état d'une entité métier pour la conformité et l'analyse en temps réel.

### Décision
Nous allons adopter l'Event Sourcing pour le service de gestion des commandes. Au lieu de stocker l'état actuel d'une commande, nous stockerons une série d'événements (par ex., `CommandeCreee`, `ArticleAjoute`, `CommandeExpediee`).

### Conséquences
* **Positives** : Piste d'audit complète ; mise en œuvre plus facile de CQRS ; support de la rejouabilité des événements pour le débogage.
* **Négatives** : Complexité accrue dans la reconstruction de l'état ; cohérence éventuelle dans les modèles de lecture ; courbe d'apprentissage pour l'équipe.

Meilleures pratiques pour l'adoption

Pour rendre les ADRs efficaces, suivez ces directives :

Gardez-les légers : Un ADR doit être un résumé, pas une thèse. Si vous vous retrouvez à écrire plus d'une page, envisagez de lier vers des spécifications techniques détaillées.
Créez-les de manière proactive : Discutez de l'ADR lors de votre réunion de conception, puis rédigez-le. Ne le laissez pas pour après coup.
Revoyez-les : Traitez les ADRs comme du code. Revoyez les demandes de tirage (pull requests) qui les modifient.
Lie-les : Si un nouvel ADR supersède un ancien, liez clairement les deux afin que la lignée soit évidente.

Conclusion

Mettre en œuvre les ADRs est une pratique à faible effort et à haut rendement. Elle transforme l'architecture logicielle d'une boîte noire en une discipline transparente et apprenable. En capturant le contexte et la justification de vos décisions, vous construisez une base de connaissances résiliente qui permet à votre équipe de prendre de meilleures décisions aujourd'hui et de comprendre votre système demain. Commencez petit : choisissez une récente décision majeure et rédigez un ADR pour elle dès aujourd'hui.