Come riconoscere una dipendenza operativa
Il segnale più chiaro non è che una persona scriva molto codice. È che un'attività ricorrente si fermi quando non è disponibile: correggere un difetto, preparare una build, aggiornare un cliente, recuperare un dato o spiegare perché una funzione si comporta in un certo modo. Il team può possedere il repository e avere comunque poca autonomia sul prodotto.
Altri segnali sono rilasci eseguiti seguendo istruzioni verbali, ambienti che nessuno sa ricreare, eccezioni gestite solo nella memoria dell'esperto e modifiche che richiedono telefonate prima ancora di poter essere stimate. La conseguenza riguarda servizio e capacità di evoluzione: i tempi diventano difficili da prevedere, ogni nuova richiesta compete per l'attenzione della stessa persona e il trasferimento di responsabilità si rinvia continuamente.
La persona che conosce il sistema ha spesso mantenuto clienti e prodotto per anni. Coinvolgerla come fonte e come revisore del trasferimento è più utile che descriverla come un ostacolo. L'obiettivo è conservare e distribuire il valore del suo lavoro, non cercare un colpevole.
Perché il repository non racconta tutto
Il codice mostra come è implementata una parte delle regole, ma non sempre spiega perché una scelta è stata fatta, quali clienti dipendono da un'eccezione, che cosa succede durante l'installazione o come rimediare a un rilascio fallito. La conoscenza passa anche da assistenza, conversazioni, revisioni, documenti e prove fatte negli anni. Uno studio empirico sul cosiddetto bus factor osserva proprio che stimare la distribuzione della conoscenza dai soli dati del controllo versione trascura altri canali. Lo studio non misura la situazione delle software house italiane; è un richiamo a non usare il numero di commit come misura completa della continuità.
A volte anche i comportamenti anomali del prodotto sono diventati aspettative dei clienti. Prima di correggerli o migrare un modulo, occorre sapere se altri flussi li danno per scontati. Le tecniche di test su sistemi esistenti, come l'individuazione di punti in cui isolare dipendenze, aiutano a osservare e proteggere quel comportamento mentre si cambia il codice.
Fonti: Jabrayilzade et al. — Bus Factor In Practice · Martin Fowler — Legacy Seam
Scenario illustrativo: il rilascio che passa sempre dalla stessa scrivania
Questo è un esempio inventato, non un caso cliente di MadeInCode. Una piccola software house mantiene un gestionale per più aziende. Il team sa sviluppare nuove schermate, ma solo una persona conosce la sequenza per generare il pacchetto, aggiornare gli archivi e verificare due installazioni particolari. Quando è in ferie, i cambiamenti attendono; quando c'è un'urgenza, il resto del lavoro si interrompe.
La prima azione utile non è riscrivere il programma. È affiancare l'esperto durante un rilascio reale, annotare prerequisiti e decisioni, ripetere la procedura in un ambiente di prova e chiedere a un secondo membro del team di eseguirla. Se un passaggio non si ripete, la documentazione è ancora incompleta. Da questa prova emergono anche i punti dove servono automazione, controlli sui dati o una procedura di ritorno.
Le cinque conoscenze da acquisire per prime
Non serve documentare ogni riga del prodotto. Conviene partire dai passaggi che fermerebbero il servizio o renderebbero impossibile una modifica sicura. Per ogni voce, indica dove si trova l'informazione, chi può verificarla e qual è la prova pratica che dimostra di averla capita.
- Mappa di moduli e dati: quali componenti esistono, quali archivi usano, come comunicano e quali integrazioni alimentano altre attività.
- Ambiente e build: strumenti, versioni, dipendenze e procedura per ottenere un artefatto installabile da una copia pulita del codice.
- Flussi critici ed eccezioni: operazioni che i clienti eseguono ogni giorno, varianti per cliente e risultati attesi su dati di prova.
- Accessi e fornitori: ruoli, sistemi esterni, scadenze e modalità sicure per ottenere le credenziali quando servono; le password non vanno copiate nella documentazione condivisa.
- Rilascio e ripristino: sequenza di installazione, controlli dopo il rilascio, backup verificato e condizioni per tornare alla versione precedente.
Dalla spiegazione orale a una prova ripetibile
Una sessione di affiancamento funziona meglio se segue un compito concreto. L'esperto esegue un'operazione e spiega le scelte non ovvie; un collega annota prerequisiti, passaggi e punti in cui si decide in base al contesto. Poi il collega ripete il compito senza suggerimenti, nell'ambiente di prova. Le differenze tra istruzioni e realtà diventano correzioni della procedura.
Per i flussi del prodotto, la prova può essere un test di caratterizzazione: fissare input e risultato attuale di un comportamento importante, anche quando l'implementazione non è elegante. Il test non dimostra che ogni regola sia corretta, ma avvisa se un cambiamento altera ciò che gli utenti ricevono. Quando non è possibile testare direttamente un modulo, si individuano punti di osservazione o separazione delle dipendenze e si costruisce una base di verifiche progressiva.
La documentazione deve vivere vicino al lavoro: essere aggiornata durante un rilascio, collegata alle decisioni che la cambiano e rieseguita periodicamente. Un manuale scritto una volta e mai provato dà una falsa sensazione di controllo. La prova decisiva è che una seconda persona completi davvero l'attività con gli strumenti e le autorizzazioni previste.
Checklist: se l'esperto fosse assente per un mese
Usa le domande come esercizio, non come valutazione della persona. Segna «sì» soltanto se qualcuno del team ha eseguito l'operazione in un ambiente appropriato e il risultato è stato verificato. Dove la risposta è «non ancora», hai trovato un buon candidato per il prossimo lavoro di documentazione o test.
- Riusciamo a creare una build da una copia pulita del codice e a identificare le versioni delle dipendenze?
- Riusciamo a spiegare i tre flussi più importanti per i clienti, comprese le loro eccezioni?
- Riusciamo a ripristinare un backup di prova e a verificare che i dati siano utilizzabili?
- Riusciamo a riprodurre e correggere un difetto semplice senza cambiare altri comportamenti?
- Riusciamo a distribuire una versione in prova, controllarla e tornare alla precedente se necessario?
- Sappiamo chi autorizza l'accesso a sistemi, fornitori e ambienti, senza dipendere da credenziali personali non condivisibili?
Cominciare dai flussi che tengono in piedi il prodotto
Le risposte negative alla checklist non chiedono un progetto infinito di documentazione. Ordina i flussi per impatto sui clienti e frequenza del cambiamento. Parti da build, rilascio e una funzione critica; rendili ripetibili; poi estendi il lavoro. Questo crea una base per nuove integrazioni, accesso web e migrazioni future senza trasformare ogni modifica in un salto nel buio.
Il Legacy Assessment di MadeInCode aiuta a ricostruire componenti, dipendenze e conoscenza che oggi non si trasferisce. Il QA Assessment affronta i flussi importanti: chiarisce i comportamenti attuali, individua quelli da preservare e introduce verifiche prima di modificarli. Quando serve una collaborazione continuativa, il Modernization Partner può aiutare a mantenere questa disciplina nei rilasci successivi.