Best practice per la consegna del codice legacy

Tra un paio di mesi un collega passerà a un nuovo progetto e erediterò uno dei suoi progetti. Per prepararmi, ho già ordinato a Michael Feathers di lavorare in modo efficace con il codice legacy .

Ma questi libri e la maggior parte delle domande sul codice legacy che ho trovato finora riguardano il caso di ereditare il codice così com'è. Ma in questo caso ho effettivamente accesso allo sviluppatore originale e abbiamo un po 'di tempo per una consegna ordinata.

Alcuni retroscena sul pezzo di codice che erediterò:

• Funziona: non ci sono bug noti, ma poiché i requisiti di prestazione continuano ad aumentare, alcune ottimizzazioni diventeranno necessarie in un futuro non troppo lontano.
• Non documentato: c'è praticamente zero documentazione a livello di metodo e classe. Ciò che il codice dovrebbe fare a un livello superiore, tuttavia, è ben compreso, perché scrivo da anni contro la sua API (come una scatola nera).
• Solo test di integrazione di livello superiore: esistono solo test di integrazione che testano la corretta interazione con altri componenti tramite l'API (di nuovo, scatola nera).
• Livello molto basso, ottimizzato per la velocità: poiché questo codice è fondamentale per un intero sistema di applicazioni, molti di questi sono stati ottimizzati più volte nel corso degli anni ed è estremamente basso livello (una parte ha il proprio gestore di memoria per determinate strutture / record).
• Concorrente e senza blocco: anche se ho molta familiarità con la programmazione concorrente e senza blocco e ho effettivamente contribuito con alcuni pezzi a questo codice, questo aggiunge un altro livello di complessità.
• Base di codice estesa: questo particolare progetto è composto da più di diecimila righe di codice, quindi non potrò farmi spiegare tutto.
• Scritto in Delphi: Sto solo per pubblicarlo, anche se non credo che la lingua sia pertinente alla domanda, poiché credo che questo tipo di problema sia indipendente dalla lingua.

Mi chiedevo come sarebbe meglio trascorrere il tempo fino alla sua partenza. Ecco un paio di idee:

• Ottieni tutto da costruire sulla mia macchina: anche se tutto dovrebbe essere controllato nel controllo del codice sorgente, che non ha dimenticato di archiviare un file di tanto in tanto, quindi questo dovrebbe probabilmente essere il primo ordine del giorno.
• Altri test: mentre vorrei più test unitari a livello di classe in modo che quando apporterò modifiche, qualsiasi bug che introduco possa essere colto all'inizio, il codice come è ora non è testabile (classi enormi, metodi lunghi, troppi mutue dipendenze).
• Cosa documentare: penso che per i principianti sarebbe meglio concentrare la documentazione su quelle aree del codice che sarebbero altrimenti difficili da capire, ad esempio a causa della loro natura di basso livello / altamente ottimizzata. Temo che ci siano un paio di cose che potrebbero sembrare brutte e bisognose di refactoring / riscrittura, ma in realtà sono ottimizzazioni che sono state là fuori per una buona ragione che potrei perdere (cfr. Joel Spolsky, Cose che dovresti Never Do, Part I )
• Come documentare: penso che alcuni diagrammi di classe dell'architettura e diagrammi di sequenza di funzioni critiche accompagnati da una certa prosa sarebbero i migliori.
• Chi documentare: mi chiedevo cosa sarebbe stato meglio, fargli scrivere la documentazione o farmelo spiegare, così posso scrivere la documentazione. Temo che le cose che sono ovvie per lui, ma non per me, non sarebbero altrimenti coperte adeguatamente.
• Rifattorizzare usando la programmazione in coppia: questo potrebbe non essere possibile a causa di vincoli di tempo, ma forse potrei refactificare parte del suo codice per renderlo più mantenibile mentre era ancora in giro per fornire input sul perché le cose sono come sono.

Si prega di commentare e aggiungere a questo. Dal momento che non c'è abbastanza tempo per fare tutto questo, sono particolarmente interessato a come dare la priorità.

Aggiornamento: al termine del progetto di consegna ho ampliato questo elenco con le mie esperienze personali in questa risposta di seguito .

Quando hai accesso allo sviluppatore, chiedi codice: -

• Quali moduli sono stati i più difficili da codificare / implementare. Quali sono stati i problemi e come sono stati superati.

• Quali moduli hanno generato il maggior numero di bug.

• Quali moduli hanno causato i bug più difficili da risolvere.

• Di quali frammenti di codice è più orgoglioso.

• Quali frammenti di codice vorrebbe davvero rifattare, ma non ha avuto il tempo.

Queste domande ti daranno un'idea di ciò che ti causerà la maggior parte dei problemi e, forse ancora più importante, una gestione dei processi di pensiero e delle prospettive sviluppatore originale.

Dato che il progetto di consegna è terminato, penso che mi prenderei il tempo e scrivo la mia risposta contenente quelle cose che hanno funzionato meglio per me.

• Ottieni tutto sotto il controllo della versione: dopo essermi accertato che tutto ciò di cui avevo bisogno per costruire fosse sotto il controllo della versione, ho anche cercato sul vecchio disco rigido dello sviluppatore, per cercare script o utilità aggiuntivi che sarebbero stati utili per distribuire e / o testare l'applicazione ma non erano non registrato.
• Top-down: vorrei iniziare con uno sguardo di alto livello sulle classi principali e una visita guidata con il vecchio sviluppatore delle aree principali. Poi avrei scavato più a fondo nel resto da solo, segnalando cose che non avevano senso per me con i //TODOpennarelli.
• Scrivi da solo tutta la documentazione: mentre il vecchio sviluppatore controllava la mia scrittura per assicurarmi di averla bene, ho insistito per scrivere tutto da solo. In questo modo sarei sicuro che la scrittura avesse un senso per me e non solo per il vecchio sviluppatore.
• Commenti ovunque: ho aggiunto riassunti della documentazione XML a ogni classe e ogni metodo. In questo modo mi sono assicurato di aver almeno guardato ogni pezzo di codice e di avere abbastanza comprensione per riassumere ciò che ha fatto in una frase. Ha inoltre reso più semplice la comprensione dei metodi utilizzando metodi / classi di riepilogo in quanto IntelliSense raccoglie queste informazioni. Potrei anche facilmente identificare le aree del codice che ancora dovevo guardare.
• Documento vicino alla fonte: per facilitare la connessione tra il codice sorgente e la documentazione, ho inserito la maggior parte della mia documentazione nel codice sorgente. Per la documentazione di alto livello che descrive l'interazione tra vari sottosistemi, ho usato un wiki, poiché mettere queste informazioni in un solo posto nel codice non ha funzionato. Tutta la documentazione deve essere elettronica e ricercabile a testo integrale.
• Diagrammi: per una panoramica di base ho usato diagrammi di classi di varie granularità per i diversi sottosistemi. Per le parti simultanee, i diagrammi di oggetti e di interazione sono stati davvero utili; vedi anche la mia altra domanda sull'argomento .
• Refactoring in coppia: mentre facevo un po 'di refactoring con il vecchio sviluppatore per avere un'idea del codice e rendere le cose più sostenibili, questo è stato un processo che richiede tempo e anche rischioso, a causa della mancanza di buoni strumenti di refactoring e di un mucchio di cattivi dipendenze tra le varie parti. Lavorare efficacemente con il codice legacy di Michael Feathers è davvero di grande aiuto, anche se il refactoring senza un adeguato supporto degli strumenti è ancora doloroso. Durante il refactoring gli avrei lasciato il controllo del mouse e della tastiera, poiché era più divertente per lui in questo modo (vedi anche il mio ultimo punto elenco) ed ero libero di scrivere ciò che stavo imparando.
• Check-in separati per commenti e modifiche: dopo aver accidentalmente introdotto un bug scrivendo un commento su un override, sono stato attento a fare commenti e modifiche in check-in separati. Ho usato una piccola utility per rimuovere tutti i commenti dal codice sorgente prima di fare il check in, quindi un diff di un check-in solo per i commenti mostrerebbe 0 differenze. Tutte le modifiche (ad es. Rimozione di campi inutilizzati) sono state attentamente sottoposte a revisione paritaria con il vecchio sviluppatore per assicurarsi che non stavo rimuovendo le cose che erano ancora necessarie.
• Procedura dettagliata per passaggi critici: per i passaggi più ottimizzati / complessi, analizzerei il codice riga per riga con il vecchio sviluppatore e talvolta anche con un terzo collega. In questo modo ho avuto una comprensione approfondita del codice e man mano che più persone controllavano il codice, abbiamo effettivamente identificato alcuni bug e alcune cose che potrebbero essere ulteriormente ottimizzate.
• Sii veloce e mantieni motivato il vecchio sviluppatore: ho notato che il vecchio sviluppatore era sempre meno interessato mentre il suo ultimo giorno si stava avvicinando (non sorprendentemente). Pertanto mi assicurerei che le parti più critiche vengano consegnate per prime, lasciando il resto per me da solo, se necessario. Ho anche cercato di lasciare a lui le cose più divertenti (ad esempio il controllo della tastiera durante la programmazione in coppia) e di fare cose noiose come la documentazione che mi scrive.
• Identifica le richieste di funzionalità: ho trovato utile chiedere al vecchio sviluppatore un elenco di funzionalità richieste dalle persone ma che non sono state ancora aggiunte. C'erano alcune cose che a me sembravano semplici da aggiungere, ma dove c'era una buona ragione per cui non venivano aggiunte in quanto avrebbero rotto altre cose quando implementate nel modo in cui inizialmente avevo pensato.

Essendo stato in una situazione simile, credo che valga la pena prendere in considerazione anche quanto segue:

• Assicurati di poter effettuare e testare una distribuzione: esegui la tua distribuzione del prodotto da zero - e verifica che ciò sia identico a quello fatto dalla persona che sta per partire. Ciò assicurerebbe che tutti gli script e le istruzioni siano chiari all'utente e verrebbero rilevati svantaggi accidentali come ingredienti che non erano stati registrati nel sistema di controllo della versione. (Non sto dicendo che questo sarebbe accaduto, solo che se ha successo, sarà molto più facile da affrontare ora, prima che la persona lascia)

  (Questo potrebbe non essere rilevante per te, ad esempio se fai già l'integrazione continua o la distribuzione continua, ma vale la pena menzionarlo, nel caso ...)

• Scrivendo più test: Questo è un davvero buon modo per testare la comprensione di un sistema. Ti consentirà (o forzerà) di guardare più da vicino le aree del codice e confermerà che il codice è privo di bug come sospetti, o rivelerà aree in cui pensavi di aver capito l'intenzione, ma che in realtà tu è necessario chiedere chiarimenti al collega prima che se ne vada

• Scrittura in coppia della documentazione: questo è un modo efficace per scrivere panoramiche. Sto suggerendo di convincere il tuo collega a descrivere una caratteristica o un'area, e poi a scriverlo, nella documentazione, con parole tue. Abbiamo scoperto che ciò era enormemente più semplice se fatto da due persone insieme.

Metterei la scrittura di test come una priorità più alta rispetto alla scrittura di documentazione, personalmente, poiché i test probabilmente ti daranno più comprensione - o più solida -.

Per quanto riguarda il refactoring utilizzando la programmazione in coppia , l'unica cosa che direi è che esiste il pericolo che questo possa diventare un pozzo senza fondo, soprattutto dato che hai detto che hai solo test di alto livello. Potresti scoprire che finisce usando molto più tempo del previsto.

+1 per le risposte che hai già nella tua domanda!

Il tour guidato
10k righe di codice è molto, ma penso che non sia ancora impossibile farti fare un "tour guidato" dall'altro. Ti siedi insieme di fronte al codice e ti accompagna in un viaggio dall'alto verso il basso, lavorando sugli "strati". Avresti bisogno di farlo in brevi raffiche - tutto in una volta ucciderebbe entrambi.

Zoom-in, zoom-out
Il vantaggio di farlo è che mentre te lo sta spiegando, avrà quasi sicuramente dei momenti "oh, sì, c'è anche questo" che potrebbe non fare se stesse solo cercando di documentarlo per conto suo. E le tue domande ti aiuteranno a concentrarti sui bit ovvi a lui ma non a nessuno. Questo tipo di interazione zoom-in / zoom-out è possibile solo uno contro uno, il tentativo di scrivere o leggere qualcosa del genere è ingombrante.

Documentazione
Penso che dovresti entrambi documentare in modo indipendente le cose - dovrebbe iniziare dal basso (nel caso in cui non hai tempo di arrivarci insieme) e dovresti iniziare dall'alto, sulla base di ciò che hai capito la sua visita guidata e come se fosse per qualcun altro [in un precedente lavoro ho ereditato un sacco di codice "legacy", e ho appena avuto il tempo di documentarlo prima di lasciarmi :)].

Dov'è cosa?
Lo scopo della maggior parte di questo è che tu possa avere un'idea di dove accadono le cose. Quindi, dato un particolare bug o modifica, puoi trovare molto rapidamente il posto nel codice su cui devi concentrarti. Puoi metterti alla prova prendendo l'elenco dei vecchi bug e vedendo se riesci a prevedere con precisione dove si trovava il problema.

Pompalo a secco
Non importa se finisce per odiarti (sorridi), il tuo compito è quello di ottenere dal cervello di quel ragazzo quante più informazioni possibili nel tempo disponibile. Assicurati di avere la gestione dalla tua parte e che diano la priorità al trasferimento delle conoscenze su "solo sistemando quegli ultimi pochi bug prima che se ne vada" (a meno che tu non li risolva insieme ...).

Suggerisco quanto segue (oltre a ciò che è già stato identificato): in primo luogo, chiedi al tuo manager di darti il ​​tempo di lavorare con questo ragazzo il più possibile e di provare a sederti con lui ogni volta che gli viene assegnato il compito di fare un cambiamento. Non devi sapere tutto quello che sta facendo, ma cerca di catturare il più possibile. Più importante essere amici con lui.

Tratta la consegna come un progetto, metti in atto un piano e coinvolgi la direzione.

0 - Assicurati di sapere come usare il sistema.

1 - Fai un inventario chiaro dei componenti della soluzione, la fonte di ciascuno e dove si trova (in diversi repository)

2 - Ottieni e, se possibile, gestisci, le password per i diversi server a partire da ora. Assicurati di avere tutte le informazioni sull'account amministratore

3 - Ottieni le licenze di ciascun componente esterno a meno che non sia al di fuori del tuo ambito (es. DLL speciali, database, ecc.)

4 - Ricevi una relazione scritta sullo stato corrente del sistema dallo sviluppatore e dai tuoi clienti (se sono locali per la tua azienda)

5 - Ottieni la documentazione per le regole aziendali, le formule di calcolo, ecc. Puoi farlo con lui. Chiedigli di e-mail, informazioni sulle riunioni, documenti sui requisiti degli utenti, documenti di progettazione e simili da fornirti.

6 - Ottieni un elenco di eventi programmati (esecuzioni mensili di lavori, esecuzioni settimanali di lavori) a cui il software deve rispondere

7 - Impara le procedure di backup / ripristino

8 - Comprendere i framework utilizzati nella costruzione dell'applicazione

9 - Scopri le modifiche richieste / previste / pianificate e lo stato di eventuali richieste degli utenti in sospeso. Inizia a cercare di identificare come fare da solo.

10 - Assicurati che i tuoi ambienti di test e sviluppo siano molto simili.

11 - Prova a identificare le principali dipendenze (su altri sistemi o tra componenti) che non possono essere individuate facilmente.

12 - Identificare e documentare le versioni richieste di ciascun utilizzo del software e il relativo contatto del fornitore (se necessario)

13 - Identifica tutti gli strumenti speciali che stava usando che non hai, nel caso ti possano aiutare.

14 - Ottieni un flusso di sistema di alto livello. e inizia a costruire la tua libreria di documentazione

15 - Comprendere come gestire la sicurezza degli utenti per l'applicazione

16 - Ottieni il registro dei bug e prova a capire le azioni e il modo in cui l'azione ha influenzato i dati più vecchi (se applicabile)

17 - Conoscere i processi che richiedono troppo tempo e cosa è necessario cercare (ad esempio dimensioni di file insolite, ftp di file duplicati, ecc.) Ove applicabile.

18 - Controllare l'orologio del server di produzione

19 - Identifica dove si trovano le configurazioni e confronta ogni configurazione di ambiente con la produzione per sapere quali parametri sono diversi e perché

20 - Ottieni le informazioni di contatto di questo ragazzo

21 - Se il sistema è interno, pianificare un incontro con gli utenti del sistema (è necessario sapere chi sono e quale ruolo svolge ciascuno) e essere presentati a loro. Ascolta cosa hanno da dire sul sistema e sui loro eventuali problemi attuali. Assicurati di essere incluso nelle e-mail il più presto possibile (dopo l'approvazione del tuo manager)

22 - Valuta la tua comprensione 1 settimana prima della sua partenza e segnala eventuali problemi che ritieni siano a rischio

Dal momento che hai detto che non hai un database, questo elenco è stato più breve.

In bocca al lupo.

Considererei innanzitutto le parti più complicate e ottimizzate per le prestazioni. Vorrei che prima documentasse quelle parti e te le spiegassero una alla volta, quindi proverei a scrivere test contro quelle parti (inclusi prima e dopo i test delle prestazioni, in modo da poter vedere se una nuova ottimizzazione rende le cose migliori o peggiori ) e chiedere all'altra persona di rivedere i test. In questo modo, documenta e spiega, usi la spiegazione per scrivere test (mentre sta documentando un'area diversa), e la sua recensione ti aiuterà a capire cosa dovresti testare. In questo modo si ottiene anche una copertura di test aggiuntiva per alcune delle parti più critiche dell'applicazione e la documentazione delle ottimizzazioni delle prestazioni specializzate.

Se ci fosse tempo dopo averli esaminati, passerei poi a un processo simile con le parti dell'applicazione che hanno avuto più frequentemente bisogno di cambiare nel corso degli anni ma che non sono nel primo gruppo di cose documentate.

Quindi documenta tutto ciò che è rimasto.

Penso che il modo migliore per acquisire un codice di grandi dimensioni sia l'approccio top-down. Cerca di capire prima il quadro generale, quindi scava gradualmente a fondo i componenti uno per uno.

Ora ad ogni livello di scavo, chiedigli di dare la priorità alle parti che richiedono più attenzione. Chiedigli di spiegarti il ​​più possibile, ma documentalo sempre da solo.

La parte migliore della documentazione da te è che quando torni più tardi, non avrai problemi a ricordare lo stesso stato cognitivo in cui ti trovavi, quando te lo ha spiegato. Puoi capire molto più facilmente ciò che hai scritto rispetto a quello che ha fatto qualcun altro. Nella mia esperienza, due persone che documentano lo stesso codice non producono pezzi di testo simili.

Questo, immagino risolva anche i tuoi problemi "cosa e come documentare". Quando ti spiega tutto, puoi decidere tu stesso cosa vorresti essere documentato quando torni al codice e documentare solo quelle parti.

L'idea è di capire prima completamente il codice (in sua presenza), quindi scrivere / fare tutto ciò che ti permetterà di farlo in seguito (in sua assenza).

Comprendendo completamente il codice intendo che è necessario avere un'idea del quadro generale e di come ciascun componente si collega a questo quadro generale. Ho trovato particolarmente utile tenere traccia di come ogni pezzo aggiunge l'insieme. Non cercare di comprendere nulla in isolamento - non perdere mai di vista il suo contesto.

Infine, una volta fatto quanto sopra, prendi il controllo in modo proattivo. Decidi tu per quali pezzi hai bisogno di copertura unit-test. quali parti devono essere (o possono essere) ottimizzate, come è possibile eseguire il refactoring di alcuni componenti, ecc. Fidarsi che se si conosce il sistema, è possibile prendere tutte le decisioni una volta che è andato.

Mi sento per te.

Alcuni suggerimenti:

1. Registrate ogni conversazione con il programmatore uscente!
2. Chiedere la motivazione dietro i "grandi" problemi. È utile comprendere l'API, ma cercare le decisioni interne: perché il codice è stato partizionato così com'è? quali sono le responsabilità.
3. Fai uno sforzo per studiare davvero il codice. Quando si assumono compiti di manutenzione e supporto, a volte c'è la pressione di "studiare il codice facendo progressi". Resisti se puoi e studia davvero il codice.
4. Cerca scenari. Conosci l'API: guarda come si comporta il codice. Un esempio che viene in mente è quello di un modulo fax. Come utente dell'API, hai dovuto preparare un'immagine della pagina e inviare al codice un comando per trasmettere la pagina. Chiedere al programmatore uscente di rintracciare con te il codice per vedere come si svolge questo scenario. Quindi, ovviamente, vai allo scenario "pagina di ricezione".
5. 80/20 - prova prima a coprire gli scenari più comuni.
6. Considera una riscrittura. Se il codice è vecchio e le interfacce sono ben definite, forse la tecnologia è cambiata abbastanza da giustificarlo.
7. Odio dirlo, ma considera di cercare un nuovo lavoro.

Se si desidera una documentazione decente acquistare ragionevolmente indolore una copia di Pascal Analyzer (PAL), l' ho usato su progetti Delphi ed è stato fantastico - ora potrebbero aver suddiviso la funzionalità di documentazione in un prodotto che non conosco (Pascal Browser) quindi potresti dover acquistare entrambi (<300 USD) ma PAL è stato un ottimo strumento per capire dove venivano utilizzate le variabili da dove venivano chiamate le funzioni ecc. e per raccogliere ogni sorta di potenziali problemi con il codice.

Usa PAL per avere un'idea di come è strutturato il codice più probabilmente un elenco di circa 1000 suggerimenti suggeriti se la mia esperienza fosse qualcosa da fare. Lavorare attraverso l'elenco migliorerà la qualità del codice, lo semplificherà notevolmente e renderà la tua vita più facile per il futuro. Delphi stesso supporta il refactoring nelle ultime versioni (negli ultimi 5 anni circa). Avevi bisogno di includere tutto nel file dpr per farlo funzionare correttamente quando lo stavo facendo, quindi tienilo a mente.

Se vuoi test unitari, scarica DUnit e inizia a creare alcuni test con il codificatore originale - questo è probabilmente un modo costruttivo di usare almeno un po 'del loro tempo.

Anche se non hai menzionato un database back-end, ma supponendo che ce ne sia uno che dovresti

1. Ottieni il modello di dati documentato in particolare le colonne e PK-FK
2. Imposta una traccia sql e registra tutte le query che vengono attivate durante l'utilizzo dell'applicazione. L'ordine di esecuzione delle query ti darà una buona idea sul flusso dell'applicazione e ti aiuterà anche nel debug

Sono nella stessa situazione in cui il nostro architetto si è trasferito in Australia e ha lasciato molta eredità come era con la compagnia degli ultimi 8 anni. Lui stesso ha ereditato roba ereditaria dal precedente architetto che era un appaltatore.

Tu e altri avete già menzionato aspetti positivi, ma qui ci sono problemi che abbiamo affrontato dopo che se ne sarebbe andato, potreste prepararvi meglio ...

1) (Persona tecnica) Dati di contatto dei clienti con cui ha a che fare.

2) Il suo account con il quale ha acquistato licenze software, chiavi che devono essere rinnovate ogni anno e processi / costi per rinnovarle.

3) Documento di installazione di librerie / componenti e prodotti software di terze parti che si integrano con i tuoi prodotti. Abbiamo lottato per 4 giorni per riportare indietro una macchina che era stata persa a causa dell'IT che ha liberato spazio e alcune istruzioni errate sono state trasmesse a loro.

4) Documenti / passaggi utilizzati per depositare il codice sorgente presso le società di deposito software, ad esempio l'impegno.

5) C'è ancora un lungo elenco ma potrebbe non essere applicabile anche a te Nessuna quantità di documentazione può sostituire una persona reale, quindi tieni i suoi dati a portata di mano, rimani in buone condizioni e buona fortuna :)

Inoltre non so se questa è la prima volta per te. Per me ho lavorato con 5/6 datori di lavoro e ho sempre ereditato il codice con una cattiva documentazione o nessuna documentazione. Quindi, insieme a tutta la documentazione, resta positivo :)