Cos'è il debito tecnico e come si gestisce

"Abbiamo troppo debito tecnico" è una frase che si sente in ogni team di sviluppo, e che quasi sempre significa "il codice non mi piace". Il concetto originale però è più preciso e molto più utile: è una metafora finanziaria, e presa sul serio spiega sia perché a volte conviene indebitarsi, sia come si convince qualcuno a lasciarti ripagare il debito.

Cos'è

Il debito tecnico è il costo futuro implicito di una scelta tecnica presa oggi per andare più veloci. Come un debito finanziario, ha un capitale e degli interessi: gli interessi sono il tempo in più che ogni modifica futura costerà.

La metafora è di Ward Cunningham, ed è importante notare cosa diceva davvero: non parlava di codice scritto male. Parlava della differenza tra il modo in cui il codice è strutturato e il modo in cui oggi capiamo il problema.

È una distinzione che cambia la conversazione: il debito non nasce solo dalla fretta, nasce anche dall'imparare cose nuove sul dominio.

Non è sempre un errore

Indebitarsi a volte è la scelta giusta, esattamente come in finanza.

I casi in cui ha senso:

Devi validare un'idea. Se non sai ancora se qualcuno vuole il prodotto, costruirlo con un'architettura impeccabile è ottimizzare la cosa sbagliata — vedi cos'è un MVP.

C'è una scadenza reale con conseguenze concrete.

Il codice potrebbe essere buttato. Non ha senso rifinire qualcosa che tra un mese non esisterà.

La conoscenza mancante. A volte capisci come andava fatto solo dopo averlo fatto.

La distinzione che conta è tra debito consapevole e debito accidentale:

	Consapevole	Accidentale
Origine	Decisione presa	Non ci si è accorti
Documentato	Sì	No
Gestibile	Sì	Solo quando esplode

Il debito consapevole è uno strumento. Quello accidentale è un problema. E la differenza pratica sta quasi tutta in una cosa: averlo scritto da qualche parte.

Come riconoscere quello che costa

Non tutto il debito va ripagato: una parte non ti costerà mai nulla, perché sta in codice che nessuno toccherà più.

I segnali che indicano debito costoso, cioè quello su cui stai davvero pagando interessi:

Le stime raddoppiano. Una modifica che sembrava da un giorno ne richiede tre, sistematicamente e sempre nella stessa area.

Cambiare una cosa ne rompe un'altra scollegata. Sintomo di accoppiamento eccessivo.

Nessuno vuole toccare quel file. Se in un team c'è una zona che tutti evitano, hai individuato il debito peggiore.

Le stesse spiegazioni si ripetono. Se ogni persona nuova richiede due ore di spiegazioni sullo stesso modulo, quel modulo sta costando ogni volta.

Gli incidenti si concentrano. Se il 70% dei problemi arriva dal 10% del codice, sai dove intervenire.

Il criterio operativo: il debito costoso è quello su codice che cambia spesso. Codice pessimo ma stabile e funzionante non ti costa quasi nulla — lasciarlo stare è una decisione legittima, non una resa.

Come si ripaga

Il grande rifacimento non funziona. Il progetto di riscrivere tutto da zero è, statisticamente, il modo più affidabile di perdere sei mesi e ritrovarsi con un sistema nuovo che ha problemi diversi.

Gli approcci che funzionano:

La regola del campeggiatore. Ogni volta che tocchi una parte di codice, lasciala un po' meglio di come l'hai trovata. Piccoli miglioramenti continui, dentro il lavoro normale.

Ripaga dove stai già lavorando. Se devi modificare un modulo, quello è il momento giusto per sistemarlo — hai già il contesto in testa.

Riserva una quota costante. Alcuni team dedicano il 10-20% di ogni ciclo di lavoro alla manutenzione. Il vantaggio è che diventa parte del processo invece di una richiesta da negoziare ogni volta.

Aggiungi test prima di modificare. Su codice che fa paura, i test sono ciò che rende sicura la modifica. È il passaggio che rende possibile tutto il resto — vedi cosa sono i test.

Strangola invece di riscrivere. Costruisci il nuovo accanto al vecchio e sposta gradualmente il traffico, un pezzo alla volta. Più lento ma reversibile a ogni passo.

Il ragionamento tecnico sul come è in cos'è il refactoring.

Come giustificarlo a chi decide

Questa è la parte che gli sviluppatori fanno peggio, e che determina se il debito verrà mai ripagato.

"Il codice è brutto" non è un argomento. Chi decide il budget non compra estetica del codice, e ha ragione.

Traduci in tempo e rischio:

• "Ogni modifica a quel modulo costa il triplo del normale."
• "Il 60% delle segnalazioni urgenti arriva da quell'area."
• "Una persona nuova impiega due settimane invece di tre giorni a diventare produttiva."
• "Non possiamo aggiornare quella libreria, e ha vulnerabilità note."

Porta numeri. Quanto tempo è stato speso su quell'area negli ultimi tre mesi? Quanti incidenti? Sono dati che di solito esistono già nel sistema di gestione delle attività.

Proponi un intervento delimitato. "Serve un mese di refactoring" viene rifiutato. "Due giorni su questo modulo, e le modifiche future in quell'area costeranno la metà" viene approvato.

E ammetti quando non conviene. Riconoscere che una parte del debito non va ripagata rende molto più credibile la richiesta su quella che conta.

Gli errori tipici

Chiamare debito tecnico qualunque cosa non piaccia. Il codice scritto con uno stile diverso dal tuo non è debito. Svaluta il termine e rende più difficile far passare i casi veri.

Ripagare il debito sbagliato. Rifinire codice che nessuno tocca è tempo speso a zero.

Accumulare senza registrare. Il debito consapevole va scritto: un commento, una nota, una voce nel sistema di attività. Altrimenti diventa accidentale.

Aspettare "quando avremo tempo". Non arriverà mai. O è nel processo, o non si fa.

Confonderlo con i bug. Un bug è qualcosa che non funziona. Il debito è qualcosa che funziona ma rende costoso il cambiamento.

In sintesi

Il debito tecnico è il costo futuro di una scorciatoia presa oggi, e come un debito finanziario matura interessi: il tempo in più che ogni modifica costerà.

Non è sempre un errore. Indebitarsi consapevolmente per validare un'idea o rispettare una scadenza reale è una scelta legittima — a patto che sia registrata. La distinzione che conta è tra debito consapevole (uno strumento) e accidentale (un problema).

Non tutto va ripagato: quello costoso è il debito su codice che cambia spesso. Codice brutto ma stabile può restare dov'è.

Si ripaga con miglioramenti continui dentro il lavoro normale, non con grandi riscritture — che sono il modo più affidabile di perdere mesi.

E la cosa che determina se verrà mai ripagato: saperlo tradurre in tempo e rischio per chi decide. "Il codice è brutto" non è un argomento; "ogni modifica costa il triplo" lo è.