Il debito di comprensione

Il debito tecnico ha una qualità che oggi rimpiango: si vede.

Lo riconosci mentre leggi. La funzione da quattrocento righe, il campo chiamato flag2, la logica di business finita dentro il controller, il modulo che tutti sanno di dover riscrivere e nessuno riscrive mai. Fa male al momento del contatto, e questo è esattamente ciò che lo rende gestibile: un dolore immediato è un segnale, e sui segnali si può decidere. Sai cos’hai, sai più o meno cosa costerebbe sistemarlo, e se scegli di non farlo è una scelta.

Da un paio d’anni sto vedendo accumularsi qualcosa di diverso, che non ha nessuna di queste proprietà. Lo chiamo debito di comprensione, per mancanza di un nome migliore.

Definizione

È codice corretto, funzionante, spesso scritto meglio della media del progetto che nessuno in azienda sa spiegare.

Non “nessuno ha letto”. Nessuno sa spiegare: perché quella scelta e non un’altra, quali alternative sono state scartate, cosa succede se l’input arriva in un formato leggermente diverso, quale vincolo del sistema quel pezzo sta rispettando senza dirlo. Il codice è lì e fa il suo lavoro. Il modello mentale che lo ha prodotto non è mai entrato in nessuna testa.

La differenza rispetto al debito tecnico è che qui non c’è niente da vedere. Il linter è verde. La copertura dei test è buona, perché i test li ha generati lo stesso strumento. La complessità ciclomatica è più bassa della media del repository. Nessuna metrica che usiamo oggi si accorge di questo debito, per la semplice ragione che tutte le nostre metriche guardano il codice, e il codice non ha alcun problema. Il problema è dall’altra parte, nelle persone, e lì non misuriamo niente.

Non è nuovo, è solo accelerato

Vale la pena essere onesti: questo debito è sempre esistito. La persona che se ne va portandosi via l’unico modello mentale di un sottosistema. Il modulo scritto in una notte prima della consegna e mai più guardato. La libreria integrata copiando l’esempio della documentazione e funzionante per motivi che nessuno ha indagato. Codice che nessuno capisce ne abbiamo sempre avuto.

Quello che è cambiato è il tasso di accumulo. Prima il debito di comprensione cresceva alla velocità con cui una persona poteva produrre codice senza capirlo e quella velocità era bassa, perché scrivere codice che non capisci è comunque faticoso e lento. C’era un limite fisico che faceva da freno, non per virtù ma per attrito.

Quel limite non c’è più. Oggi una persona può immettere in un sistema, in una settimana, più codice non compreso di quanto ne avrebbe prodotto in un anno. E può farlo mentre tutti gli indicatori di qualità migliorano.

Come si manifesta

Il debito di comprensione non si annuncia. Si vede di riflesso, e quasi sempre in fenomeni che attribuiamo ad altro:

La modifica piccola che nessuno vuole prendere in carico. Un cambiamento apparentemente banale su una certa area, e in pianificazione cala il silenzio. Non è pigrizia: è che nessuno sa cosa si romperà.

Le stime che si gonfiano su zone precise del sistema senza che nessuno sappia dire perché. Se chiedi, ti risponderanno “quella parte è delicata”. Delicata di solito significa opaca.

“Funziona, non toccarlo”. La frase più costosa dell’intero mestiere, e il sintomo più diretto.

I bug risolti aggiungendo codice invece che togliendolo. Chi ha il modello del sistema rimuove la causa; chi non ce l’ha aggiunge una condizione attorno al sintomo. È un indicatore che si legge nei diff, ed è piuttosto affidabile.

La riscrittura che sembra più economica della modifica. Su un componente di sei mesi fa. Quando arriva questo, il debito non è da pagare: è già stato pagato, in perdita.

Un modo per misurarlo

Non ho una metrica automatica da proporre e diffido di chi la propone. Ho un esercizio, che si fa in mezz’ora su una lavagna.

Si elencano le aree del sistema, e per ognuna si scrive quante persone sono in grado di spiegarla senza aprirla: cosa fa, perché è fatta così, cosa la rompe. Non “quante ci hanno lavorato”. Quante la sanno spiegare.

È il bus factor applicato alla comprensione anziché all’accesso, e il risultato è di solito peggiore di quanto chiunque si aspettasse soprattutto sulle parti costruite di recente e in fretta, che sono anche quelle che in retrospettiva sembravano essere andate meglio.

Cosa lo riduce

La regola del “spiegamelo”. In revisione non passa ciò che l’autore non sa spiegare, anche quando funziona perfettamente. Il criterio non è “l’ho letto”, è “so dirti cosa succede se”. Va detto chiaramente al team che questo non è un test di lealtà verso gli strumenti: vale identico per il codice scritto a mano, e ha sempre dovuto valere. È solo che prima capitava di rado di scrivere qualcosa che non si sapeva spiegare.

Documentare le decisioni, non il codice. Il codice generato è già ampiamente commentato, spesso più del necessario, e quei commenti dicono cosa fa che era la parte già leggibile. Quello che manca è il perché: quali alternative sono state considerate, quale vincolo ha deciso, cosa era vero al momento della scelta e potrebbe non esserlo più. Bastano dieci righe per decisione, tenute vicino al codice.

Chiedere le alternative scartate al momento giusto. Il momento in cui il contesto è massimo è quando il codice viene generato, non sei mesi dopo. “Cosa hai considerato e perché hai escluso il resto” è la domanda che trasforma un output in una comprensione, e costa trenta secondi allora contro tre giorni poi.

Rotazione deliberata. Chi non ha scritto una parte deve metterci le mani prima che sia un’emergenza. È l’unico modo per scoprire quanto è opaca mentre scoprirlo costa poco.

E contrarlo consapevolmente, quando serve. Come per il debito tecnico, non è la contrazione il problema. Per uno script interno, un prototipo, una cosa che vivrà tre settimane, generare qualcosa che nessuno capisce è perfettamente razionale. Il debito diventa pericoloso quando è una scoperta invece che una decisione — quando ci si accorge di averlo il giorno in cui bisogna ripagarlo.

Perché conta più di prima

Il debito tecnico ha un’ultima proprietà consolante: è ripagabile con lavoro. Anche molto, anche noioso, ma lavoro e oggi il lavoro di riscrittura costa meno di quanto sia mai costato.

Il debito di comprensione no. Non si ripaga generando altro codice, perché il codice non è mai stato il problema. Si ripaga solo con il tempo di persone che si siedono e ricostruiscono un modello mentale che nessuno ha mai avuto, partendo da un artefatto che non è stato scritto per essere spiegato. È l’unica forma di debito che gli strumenti che lo producono non aiutano a estinguere.

Il debito tecnico si vede nel codice. Il debito di comprensione si vede solo nelle persone — e per questo, quando lo vedi, di solito è tardi.