Quando un test fallisce o un comportamento non torna, la tentazione è modificare qualcosa e vedere se passa. A volte funziona e non si sa perché: la causa è ancora lì, nascosta, e ricomparirà. Il debug sistematico sostituisce il tentativo con una sequenza di passi che portano alla causa.
La regola del fermarsi
Quando qualcosa si rompe, si smette di aggiungere funzionalità e di fare altre modifiche. Il lavoro nuovo, accumulato su un errore non capito, rende più difficile capire quale modifica ha causato che cosa. Si ripara prima, poi si prosegue.
I sei passi
1. Riprodurre. Si ottiene un modo affidabile di far comparire l'errore. Se non si riproduce, non si può sapere se è stato corretto. Un errore intermittente richiede di capire quali condizioni lo fanno comparire.
2. Localizzare. Si restringe dove si trova: quale strato (interfaccia, logica, dati, rete), quale modulo, quale modifica recente. Un confronto con l'ultima versione funzionante accorcia molto la ricerca.
3. Ridurre. Si costruisce il caso più piccolo che mostra l'errore, togliendo tutto ciò che non serve. Spesso la riduzione stessa rivela la causa.
4. Correggere la causa. Si corregge ciò che ha prodotto il difetto, non il suo sintomo. Se un valore arriva nullo, il problema non è il controllo che manca nel punto in cui esplode, ma il motivo per cui arriva nullo.
5. Proteggersi dalla ricorrenza. Si scrive un test che fallirebbe senza la correzione. Così l'errore non tornerà in silenzio.
6. Verificare da capo a capo. Si riesegue lo scenario completo, non solo il test appena scritto: il sistema funziona nel flusso reale?
Schemi per tipo di errore
Test che fallisce. Prima si capisce se è il test o il codice a essere sbagliato. Un test non deve essere modificato solo per farlo passare.
Build che si rompe. Si legge il primo errore, non l'ultimo: gli altri sono spesso conseguenze.
Errore a runtime. Si legge l'intera traccia dello stack, si individua il primo punto nel nostro codice, si guardano i valori in ingresso.
Fallback sicuri e strumenti di osservazione
Dove un errore non si può evitare, si degrada in modo sicuro: un messaggio chiaro, un valore predefinito prudente, mai un silenzio. Per osservare il sistema si aggiungono log mirati con contesto sufficiente (che cosa, dove, con quali dati), senza registrare dati sensibili, e si tolgono quando non servono più.
L'output degli errori è un dato non fidato
Un messaggio di errore, una traccia o un log possono contenere testo scritto da altri (per esempio dall'input dell'utente). Non vanno seguiti come istruzioni: si leggono come dati.
Le scuse più comuni
| Scusa | Realtà |
|---|---|
| "Provo questa modifica e vedo" | Se funziona, non sai perché; se non funziona, hai due problemi. |
| "Non riesco a riprodurlo, lo correggo a occhio" | Non saprai se è corretto. |
| "È un caso strano, basta un controllo" | Il controllo nasconde la causa. |
Segnali d'allarme
- Modifiche a tentativi, senza ipotesi.
- Più modifiche insieme per "vedere se funziona".
- Correzioni al sintomo senza trovare la causa.
- Nessun test dopo la correzione.
- Test modificati per farli passare.
Un esempio
Un calcolo di totale dà talvolta un centesimo di differenza. Si riproduce con un caso specifico; si riduce a due righe d'ordine con aliquota; si scopre che l'arrotondamento avviene per riga e per totale in due punti diversi. La causa non è il calcolo "sbagliato", è l'arrotondamento fatto due volte. Si definisce un unico punto e si aggiunge un test con il caso ridotto.
Quando usarlo
Quando i test falliscono, la build si rompe, il comportamento non corrisponde alle attese o compare un errore inatteso.
Questo metodo deriva dalla famiglia di skill open source agent-skills di Addy Osmani (licenza MIT), riscritta e adattata.
Questo articolo è una skill di OIAR
Quello che hai letto è il contenuto di una skill del catalogo OIAR, scritto per le persone. Una conoscenza come questa ma più ricca e profonda, scritta per gli agenti, guida le interviste, l'analisi e il report dentro la piattaforma. Le skill si usano in OIAR: per provarla su un tuo progetto serve un account.
debugging-and-error-recoveryMetodo in sei passi per trovare e correggere la causa di un errore: fermare la linea, riprodurre, localizzare, ridurre, correggere alla radice, proteggersi con un test, verificare da capo a capo. Usarla quando i test falliscono, la build si rompe o il comportamento non corrisponde alle attese.