ADR : la dette documentaire que personne ne compte

Un ADR périmé est pire qu'une absence d'ADR. Sans document, le nouveau venu lit le code et pose la question. Avec un document marqué « accepté », il ne pose pas la question, il applique. Et le document a sur le code un avantage injuste, puisqu'il explique ses raisons et donc convainc.

L'ADR 12, par exemple, dit que les read models du back-office sont mis à jour dans la transaction de la commande, pour que l'écran soit toujours à jour. Dix-huit mois plus tard, les projections sont passées en asynchrone parce que les rebuilds bloquaient les écritures ; la décision a été prise dans une discussion, le code a suivi, l'ADR 12 n'a pas bougé. Un développeur arrivé le mois dernier ajoute un read model, cherche la règle, la trouve, et écrit une projection synchrone. La revue de code la laisse passer, puisqu'elle est conforme à l'ADR. Avec un agent de code à la place du développeur, à qui l'on a donné le répertoire docs/adr comme contexte, la même erreur se produit en quatre minutes, sans hésitation et dans dix fichiers.

On compte la dette du code. Celle des décisions écrites ne figure nulle part, et elle se paie de la même façon, en intérêts, à chaque lecture.

Pourquoi un ADR se périme sans bruit

La convention veut qu'un ADR ne se modifie pas ; on en écrit un nouveau qui le remplace. La règle est bonne, elle conserve l'historique des raisons, mais elle a un effet de bord. Remplacer coûte plus cher que modifier, donc on ne remplace pas. Changer le code prend une PR, alors que changer la décision demande d'écrire un document, d'en retrouver un ancien et de les relier. Rien n'échoue si on ne le fait pas.

Tout le mécanisme est là : aucun déclencheur ne relie un changement de code à l'ADR qu'il contredit. Un test cassé se voit. Un ADR contredit reste vert.