Definizione breve

Scarto tra ciò che un sistema fa e ciò che il team che ne risponde sa spiegare. Si contrae ogni volta che si accetta codice senza che nessuno sappia dire perché è scritto così, e si rimborsa in tempo speso a ricostruire un intento che nessuno ha mai formulato.

Definizione dettagliata

L'espressione ricalca il debito tecnico, di cui riprende la meccanica — un vantaggio immediato ottenuto in cambio di un costo futuro maggiorato — cambiando ciò che si prende in prestito. Il debito tecnico riguarda lo stato del codice; questo riguarda lo stato della testa di chi lo mantiene.

Negli articoli di questo blog il termine indica il rovescio dello sviluppo assistito: un team che fa il merge di codice generato, accettato e rattoppato senza che nessuno sappia spiegarlo ottiene subito funzionalità e, più avanti, un'incapacità di diagnosi. Il passivo resta invisibile finché niente si rompe, perché l'applicazione gira, le schermate rispondono e i test passano.

Il senso normativo vorrebbe un debito misurabile e rimborsabile con un intervento identificato. L'uso sul campo non conosce né contatore né scadenza: lo si constata al momento dell'incidente, quando un team scopre di non sapere più perché tutto crolla, e il rimborso passa per una rilettura che nessuno ha più il tempo di intraprendere.

Uso nel dominio

Il termine interviene nelle regole di merge — rifiutare codice che nessuno sa spiegare —, nella decisione sul budget di comprensione per ogni funzionalità (il contratto, i test, la decisione di architettura, i limiti noti) e nella diagnosi di un team il cui ritmo di correzioni aumenta senza che il prodotto cambi.

Sinonimi e varianti

«Codice non capito», «accettare codice che non si sa spiegare». Formulazioni affini usate per lo stesso passivo: «un sistema che non si è mai abitato», «un'architettura le cui decisioni nessuno ha preso».

Da non confondere con

• Debito tecnico — debolezza di progettazione che l'azienda ha deciso di trattare, e che per questo ha un costo e un posto tra le priorità; si rimborsa con lavoro di riprogettazione, mentre il debito di comprensione si paga con l'incapacità di decidere che cosa riprogettare — e aspetta una decisione per esistere, mentre questo si contrae al momento del merge.
• Ricostruibilità — proprietà di un sistema che un team saprebbe rifare altrove; è l'attivo di cui questo debito è il passivo, e la domanda «saprei ricostruirlo?» è il modo più diretto per constatare l'uno o l'altra.
• Debito documentale — assenza o obsolescenza dei documenti che descrivono il sistema; un team può aver documentato tutto senza capire niente, così come può capire tutto senza aver scritto niente.
• Bus factor — numero di persone la cui partenza renderebbe un sistema ingestibile; misura come si distribuisce una comprensione che esiste, non la sua assenza.
• Legacy — sistema ereditato le cui decisioni sono state prese altrove e prima; il debito di comprensione si accumula su codice scritto questa settimana.

Esempi

«Un team che accetta codice non capito accetta un debito di comprensione.» — l'uso di riferimento, posto come conseguenza di una regola di merge.

Decine di pull request create durante la notte da un assistente e integrate senza che nessuno abbia verificato gli impatti: il volume consegnato è passivo, non vantaggio.

Un'applicazione che supera gli scenari felici e contiene centinaia di scelte tecniche generate, accettate, rattoppate e poi dimenticate porta con sé il debito intero, anche se nessun difetto è ancora comparso.

Ambiguità / dibattiti

La parola «debito» suggerisce un importo e una scadenza che qui niente permette di stabilire: nessuna pratica attestata quantifica lo scarto tra ciò che un sistema fa e ciò che un team ne sa spiegare.

L'attribuzione resta discussa: il debito è di chi ha fatto il merge o del team che mantiene? L'uso adottato qui lo attribuisce al team, perché è il team a rimborsarlo.