Come leggere codice legacy senza perdere la testa

Il tuo team ti assegna un progetto scritto 10 anni fa, senza documentazione, con centinaia di file PHP, variabili dai nomi criptici e funzioni che si chiamano ancora processData().

Benvenuta/o nel meraviglioso mondo del codice legacy: codice vecchio, non testato, spesso scritto con tecniche superate — ma ancora perfettamente funzionante in produzione.

Come si legge codice legacy senza impazzire?
Come si capisce da dove iniziare, cosa toccare, cosa lasciare stare?

In questo articolo ti diamo strategie concrete per affrontare un progetto legacy, anche se ti sembra una giungla di parentesi, if annidati e logiche dimenticate.

1. Cambia mentalità: dal “rifare tutto” al “capire prima”

Il primo errore di chi eredita codice legacy è voler riscrivere tutto da zero.
Spesso è impossibile: mancano i test, la documentazione e, soprattutto, la conoscenza del business che quel codice riflette.

✅ Invece di rifare, studia. Fatti guidare da domande come:

• Cosa fa esattamente questo modulo?

• Chi lo usa? Quanto è critico?

• Quali parti sono più modificate nel tempo?

• Esistono test, anche parziali?

Leggere codice legacy è più un lavoro investigativo che tecnico.

2. Parti dalla struttura, non dal dettaglio

Non iniziare da una singola funzione. Parti dall’alto:

• Come sono organizzate le cartelle?

• Quali file vengono caricati per primi?

• C’è un index.php, un router, un autoload?

Se possibile, traccia il flusso di esecuzione:

1. Entry point

2. Logica principale

3. Output o redirect

Usa strumenti come:

• xdebug per capire l’ordine delle funzioni

• grep per cercare nomi e pattern ricorrenti

• Diagrammi a mano (o con strumenti come Excalidraw)

3. Documenta mentre leggi (per te e per chi verrà)

Ogni scoperta è oro. Scrivila subito.

• “Questo file gestisce l’invio mail ma include anche funzioni di login”

• “La funzione checkAll() è usata solo nel modulo fatture”

• “La tabella utenti_old non è più usata”

Usa un README locale, una wiki di progetto o un tool di knowledge sharing come Notion o Obsidian.

4. Fai test, anche se minimi

Se il progetto non ha test automatizzati, puoi:

• aggiungere log temporanei per capire cosa succede

• creare test manuali documentando le azioni da fare (es. “accedi come admin → modifica profilo → salva”)

Poco a poco, potrai anche introdurre unit test in nuove funzioni che isoli o riscrivi.

5. Refactoring graduale, non rivoluzione

Inizia con miglioramenti minimi ma preziosi:

• rinomina le variabili x1, x2, d1 → nomi descrittivi

• spezza le funzioni chilometriche in metodi più piccoli

• sostituisci codice duplicato con funzioni riutilizzabili

• isola le query SQL in repository o model

Ogni piccola azione rende il progetto più leggibile e sicuro per chi ci metterà mano dopo di te (forse proprio te tra sei mesi).

Strumenti utili

6. Parla con chi ha scritto quel codice (se puoi)

Se hai accesso alla persona o al team che ha lavorato sul progetto, fai domande:

• Perché è stata fatta questa scelta?

• Quali bug ricorrenti c’erano?

• Cosa avresti voluto cambiare?

A volte mezz’ora di confronto ti fa risparmiare giorni di debug.

Conclusione

Leggere codice legacy non è una punizione, ma un’abilità preziosa.
Serve pazienza, spirito critico e metodo.
Non serve capire tutto: basta capire abbastanza per agire senza fare danni.

E se riuscirai anche a migliorare un pezzetto di quel codice, avrai fatto un favore a te stessa e a chi verrà dopo.