Idea principale

Fare il merge di codice che nessun membro del team saprebbe spiegare non è una disattenzione in fase di revisione: è un prestito. Il team ottiene subito la funzionalità e si impegna a pagare più avanti in incapacità di diagnosi — quando bisognerà modificare, mettere in sicurezza o riprendere quel codice senza sapere perché è scritto così.

Il passivo resta invisibile finché niente si rompe: l'applicazione gira, le schermate rispondono, i test passano. Decine di pull request aperte durante la notte da un assistente e integrate senza che nessuno abbia verificato gli impatti sembrano un vantaggio guadagnato; sono interessi che maturano.

Da qui una regola di merge semplice, quasi brutale: non integrare codice che nessuno sa spiegare. Non richiede una documentazione interminabile — basta un piccolo budget di comprensione per ogni funzionalità: il contratto, i test, la decisione di architettura, i limiti noti. Quanto basta perché il ragionamento resti trasmissibile da persona a persona.

Perché è importante

Rimette un prezzo immediato sull'incomprensione, nel punto e nel momento in cui si prende la decisione. Finché il costo è differito, ogni integrazione presa da sola sembra ragionevole, e il passivo si accumula senza che nessuna scelta l'abbia accettato.

Offre anche un criterio di revisione che non dipende dal livello tecnico di chi rilegge: la domanda non è «questo codice è buono?» ma «qualcuno qui sa dire perché è fatto così?».

Sfumature e limiti

La regola si scontra con una zona grigia: spiegare fino a che livello? Nessuno spiega riga per riga il codice di una libreria di terze parti, e un team che pretendesse quel grado di dettaglio su tutto non integrerebbe più niente. Quello che va spiegato è l'intento e i confini, non ogni istruzione.

E vale solo se qualcuno ha l'autorità di bloccare un'integrazione. In un team in cui conta prima di tutto la scadenza, diventa una formalità dichiarativa, e la spiegazione si riduce a una casella spuntata.

Domande aperte

• Su quale perimetro deve vertere la spiegazione — la funzionalità, il modulo, la riga — perché la regola resti applicabile senza diventare un rituale?