Définition courte
Écart entre ce qu'un système fait et ce que l'équipe qui en répond sait expliquer. Elle se contracte à chaque fois qu'un code est accepté sans que personne ne puisse dire pourquoi il est écrit ainsi, et elle se rembourse en temps passé à reconstituer une intention que personne n'a formée.
Définition détaillée
L'expression est calquée sur la dette technique, dont elle reprend la mécanique — un avantage immédiat obtenu contre un coût futur majoré — en changeant ce qui est emprunté. La dette technique porte sur l'état du code ; celle-ci porte sur l'état de la tête de ceux qui le maintiennent.
Dans les articles de ce blog, le terme désigne la contrepartie du développement assisté : une équipe qui merge du code généré, accepté et patché sans que quiconque puisse l'expliquer obtient de la fonctionnalité tout de suite et une incapacité de diagnostic plus tard. Le passif est invisible tant que rien ne casse, puisque l'application tourne, que les écrans répondent et que les tests passent.
Le sens normatif voudrait une dette mesurable et remboursable par un chantier identifié. L'usage terrain ne connaît ni compteur ni échéance : elle se constate au moment de l'incident, quand une équipe découvre qu'elle ne sait plus pourquoi tout s'écroule, et son remboursement passe par une relecture que plus personne n'a le temps d'entreprendre.
Usage dans le domaine
Le terme intervient dans les règles de merge — refuser du code que personne ne sait expliquer —, dans l'arbitrage du budget de compréhension par fonctionnalité (le contrat, les tests, la décision d'architecture, les limites connues), et dans le diagnostic d'une équipe dont le rythme de correction augmente sans que le produit change.
Synonymes et variantes
« Code incompris », « accepter du code qu'on n'explique pas ». Tournures voisines employées pour le même passif : « un système qu'on n'a jamais habité », « une architecture dont personne n'a pris les décisions ».
À ne pas confondre avec
- Dette technique — faiblesse de conception dont l'entreprise a décidé qu'elle serait traitée, et qui porte à ce titre un coût et une place dans les priorités ; elle se rembourse en travail de refonte, là où la dette de compréhension se paie en incapacité à décider quoi refondre — et elle attend une décision pour exister, quand celle-ci se contracte au merge.
- Reconstructibilité — propriété d'un système qu'une équipe saurait refaire ailleurs ; c'est l'actif dont cette dette est le passif, et la question « saurais-je le reconstruire ? » est la façon la plus directe de constater l'une ou l'autre.
- Dette documentaire — absence ou péremption des documents décrivant le système ; une équipe peut avoir tout documenté et ne rien comprendre, comme elle peut tout comprendre sans rien avoir écrit.
- Bus factor — nombre de personnes dont le départ rendrait un système inexploitable ; il mesure la répartition d'une compréhension qui existe, pas son absence.
- Legacy — système hérité dont les décisions ont été prises ailleurs et plus tôt ; la dette de compréhension s'accumule sur du code écrit cette semaine.
Exemples
« Si une équipe accepte du code incompris, elle accepte une dette de compréhension. » — l'emploi de référence, posé comme conséquence d'une règle de merge.
Des dizaines de pull requests créées dans la nuit par un assistant et mergées sans que personne n'ait vérifié les impacts : le volume livré est du passif, pas de l'avance.
Une application qui passe les scénarios heureux et contient des centaines de choix techniques générés, acceptés, patchés puis oubliés porte la dette entière, même si aucun défaut n'est encore apparu.
Ambiguïtés / débats
Le mot « dette » suggère un montant et une échéance que rien ne permet d'établir ici : aucune pratique attestée ne chiffre l'écart entre ce qu'un système fait et ce qu'une équipe en explique.
L'attribution reste discutée : la dette est-elle portée par la personne qui a mergé, ou par l'équipe qui maintient ? L'usage retenu ici la place sur l'équipe, puisque c'est elle qui la rembourse.