Accueil › Architecture & design patterns › Pourquoi écrire une décision
Pourquoi écrire une décision
Documenter les décisionsavance
Le code dit ce qui a été fait. Il ne dit jamais pourquoi les autres options ont été écartées.
Dans deux ans, quelqu'un lira une file de messages entre deux services et se demandera pourquoi un appel direct n'aurait pas suffi. S'il ne trouve pas la réponse, il fera l'une des deux choses suivantes : supprimer la file parce qu'elle paraît inutile, ou la garder par superstition. Les deux sont mauvaises, et c'est le même manque qui les produit.
Une décision d'architecture écrite tient en une page. Elle se range à côté du code, dans le dépôt, et se relit en deux minutes.
# 7. Communiquer par file de messages entre Commandes et Facturation
Statut : acceptée — 2024-03-12
## Contexte
Facturation est indisponible plusieurs heures par mois pour maintenance.
Un appel direct depuis Commandes échoue alors à la prise de commande.
## Décision
Commandes publie un événement ; Facturation le consomme à son rythme.
## Conséquences
La facture peut arriver avec du retard. Il faut un suivi des messages
non consommés, et un traitement idempotent côté Facturation.
Ce qu'on écrit n'est pas une documentation du système. C'est la trace d'un arbitrage : une contrainte, des options, un choix, un prix accepté. Le document ne décrit pas l'architecture, il explique comment elle est devenue celle-là.
On n'écrit pas tout. On écrit ce qui est coûteux à défaire, et ce dont l'absence de raison écrite ferait recommencer le débat.
Les termes à connaître
- Décision d'architecture
Un choix structurant qui est coûteux à défaire : un découpage, un protocole, un format de stockage, une dépendance imposée à tout le code.
- ADR
Architecture Decision Record. Un fichier court, versionné avec le code, qui consigne une décision, son contexte et ses conséquences.
- Registre de décisions
L'ensemble ordonné des décisions écrites d'un projet. Il se lit dans l'ordre et raconte comment le système est devenu ce qu'il est.
- Savoir tacite
Ce que l'équipe sait sans l'avoir écrit. Il disparaît avec les personnes, et nul ne s'en aperçoit avant d'en avoir besoin.
- Décision immuable
Une décision écrite ne se corrige pas : on en écrit une nouvelle qui remplace l'ancienne, et l'ancienne reste lisible.
- Archéologie de code
L'enquête menée dans l'historique pour comprendre pourquoi une ligne existe. Elle commence quand l'intention n'a pas été écrite.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.