Pausa caffè #20. Cos'è il codice legacy e come utilizzarlo. Strumenti che semplificano la scrittura della documentazione tecnica

Cos'è il codice legacy e come utilizzarlo

Fonte: Dou Prima e poi, un programmatore dovrà probabilmente imbattersi in codice legacy. Per alleviare le conseguenze di questa conoscenza, ho selezionato alcuni suggerimenti pratici ed esempi dalla mia esperienza, in particolare lavorando con un sistema Java legacy.

Funzionalità legacy

L'eredità è il codice di qualcun altro, che spesso è così terribile che generalmente non è chiaro come lavorarci. E se devi lavorare con un sistema legacy, oltre al vecchio codice, incontrerai anche:

• con tecnologia obsoleta;
• architettura eterogenea;
• mancanza o addirittura totale assenza di documentazione.

In effetti, il codice legacy non è così spaventoso, ed ecco perché: se il sistema ha vissuto tutti questi dieci anni e funziona ancora, allora ha una certa utilità. Forse guadagna bene (a differenza della tua ultima startup). Inoltre, questo codice è relativamente affidabile se è riuscito a sopravvivere in produzione per così tanto tempo. Pertanto, le modifiche ad esso devono essere apportate con cautela. Prima di tutto bisogna capire due cose:

1. Non possiamo mancare di rispetto a un sistema che guadagna milioni o a cui accedono migliaia di persone al giorno. Non importa quanto sia stato scritto male, questo codice disgustoso è sopravvissuto alla produzione e funziona 24 ore su 24, 7 giorni su 7.

2. Poiché questo sistema porta denaro reale, lavorarci comporta una grande responsabilità. Questa non è una startup, ma qualcosa con cui gli utenti lavoreranno domani. Ciò implica anche un costo di errore molto elevato, e il punto qui non sono le affermazioni del cliente, ma la situazione reale.

Ingegneria inversa

Per lavorare con successo con il codice legacy, dovrai utilizzare tecniche di reverse engineering. Innanzitutto è necessario leggere attentamente il codice per capire esattamente come funziona. Questo è obbligatorio, perché molto probabilmente non avremo documentazione. Se non comprendiamo il pensiero dell’autore, apporteremo cambiamenti con conseguenze imprevedibili. Per proteggerti da questo, devi anche approfondire il codice adiacente. E allo stesso tempo muoversi non solo in ampiezza, ma anche in profondità. Dove viene chiamato il metodo con l'errore? Da dove viene il codice che lo richiama? In un progetto legacy, la "gerarchia delle chiamate" e la "gerarchia dei tipi" vengono utilizzate più spesso di ogni altra cosa. Dovrai dedicare molto tempo al debugger: in primo luogo, per trovare errori e, in secondo luogo, per capire come funziona il tutto. Per quanto riguarda la documentazione, non sarebbe una cattiva idea ricorrere all'archeologia industriale. Può essere molto utile ripescare da qualche parte la vecchia documentazione e parlare con chi ricorda come è stato scritto il codice che hai ereditato. Usando queste tecniche, prima o poi inizierai a capire più o meno il codice. Ma per evitare che i tuoi sforzi vadano sprecati, devi documentare immediatamente i risultati della tua ricerca. Per fare ciò, consiglio di disegnare diagrammi a blocchi o diagrammi di sequenza. Certo, sarai pigro, ma devi assolutamente farlo, altrimenti in sei mesi senza documentazione scaverai in questo codice come se fosse la prima volta.

Non riscrivere il codice

La cosa più importante nel processo di sviluppo è picchiarsi in tempo e non provare a riscrivere l'intero codice da zero. Stimare quanti anni-uomo ciò richiederà. È improbabile che il cliente voglia spendere così tanti soldi per rifare qualcosa che già funziona. Ciò vale non solo per il sistema nel suo insieme, ma anche per qualsiasi sua parte. Naturalmente, potrebbero darti una settimana per capire tutto e un'altra settimana per sistemare qualcosa. Ma difficilmente ti daranno due mesi per riscrivere parte del sistema. Implementare invece la nuova funzionalità nello stesso stile del resto del codice. In altre parole, se il codice è vecchio, non dovresti essere tentato di utilizzare nuove bellissime tecnologie: tale codice sarà poi molto difficile da leggere. Ad esempio, potresti riscontrare una situazione simile a quella che abbiamo avuto noi: parte del sistema è scritta in Spring MVC e parte è scritta in servlet semplici. E se in una parte scritta nei servlet è necessario aggiungere qualcos'altro, lo aggiungiamo allo stesso modo: nei servlet.

Rispettare gli interessi commerciali

Va ricordato che qualsiasi compito è determinato, prima di tutto, dal valore per l'azienda. Se non si dimostra al cliente la necessità di determinati cambiamenti dal punto di vista aziendale, questi cambiamenti non avverranno. E per convincere il cliente bisogna cercare di mettersi al suo posto e comprendere i suoi interessi. In particolare, se desideri eseguire il refactoring solo perché il codice è difficile da leggere, non ti sarà consentito farlo e dovrai conviverci. Se proprio non ce la fai, puoi riorganizzare il codice tranquillamente e poco a poco, distribuendo il lavoro su ticket aziendali. Oppure convincere il cliente che questo, ad esempio, ridurrà il tempo necessario per trovare gli errori e quindi, in definitiva, ridurrà i costi.

Test

È chiaro che i test sono necessari in qualsiasi progetto. Ma quando si lavora con sistemi legacy, occorre prestare particolare attenzione ai test, anche perché l’impatto delle modifiche apportate non è sempre prevedibile. Avrai bisogno di almeno tanti tester quanti sviluppatori, altrimenti dovresti essere incredibilmente bravo con l'automazione. Nel nostro progetto il testing si è articolato nelle seguenti fasi:

1. Verifica, quando la funzionalità implementata di una funzionalità viene verificata in un ramo separato.
2. Stabilizzazione, quando viene controllato un ramo di rilascio in cui tutte le funzionalità sono unite insieme.
3. Certificazione, quando la stessa cosa viene eseguita nuovamente su casi di test leggermente diversi in un ambiente di certificazione il più vicino possibile alla produzione in termini di caratteristiche e configurazione dell'hardware.

E solo dopo aver attraversato tutte queste tre fasi potremo rilasciare il rilascio. Probabilmente qualcuno pensa che la certificazione sia una fase in più, dato che tutto è già stato chiarito in fase di stabilizzazione, ma la nostra esperienza suggerisce che non è così: a volte durante un test di regressione, che viene eseguito per il secondo giro su un'altra macchina, qualcosa in qualche modo verrà fuori.

Formalizza DevOps e rilascia

La procedura di rilascio potrebbe, ad esempio, essere la seguente. Una volta completato lo sviluppo e completate due o tre fasi di test, scriviamo un'e-mail al team DevOps 36 ore prima dell'orario di rilascio previsto. Successivamente chiamiamo il team devops e discutiamo di tutte le modifiche negli ambienti (li informiamo su tutte le modifiche al database e alla configurazione). Per ogni cambio abbiamo un documento (un ticket in Jira). Poi, durante il rilascio, tutte le persone coinvolte in questo si riuniscono e tutti dicono cosa stanno facendo adesso: “Abbiamo caricato il database”, “Abbiamo riavviato questo e quest’altro server”, “Siamo andati a eseguire test di regressione nell’ambiente di produzione. " Se qualcosa va storto, viene avviata la procedura di rollback del rilascio, esattamente descritta nel documento di rilascio originale: senza tale documento dimenticheremo sicuramente qualcosa o saremo confusi.

Controllare la qualità del codice

Infine, la revisione del codice è una pratica che per qualche motivo non viene utilizzata in tutti i progetti. È fantastico se ogni pezzo di codice viene rivisto da più di una persona. Anche in un team molto forte, durante il processo di revisione del codice vengono sempre scoperti alcuni bug e, se più persone lo esaminano, il numero di bug identificati aumenta. Inoltre, a volte il terzo o il quarto revisore trovano la cosa peggiore.

Strumenti che semplificano la scrittura della documentazione tecnica

Fonte: Dzone Alla maggior parte dei programmatori non piace scrivere documentazione tecnica. L’esperto di psicologia Gerald Weinberg ha addirittura definito la documentazione “l’olio di ricino della programmazione”: gli sviluppatori adorano leggerla, ma semplicemente odiano scriverla da soli. Una mancanza di indicazioni o una tabella di marcia vuota si traducono in una mancanza di informazioni su come funzionano le diverse parti del software. Ciò alla fine peggiora l'esperienza del codice per gli utenti finali perché, in assenza di documentazione, non possono fare affidamento sull'accuratezza e sull'utilità del prodotto. Per rendere più facile per i programmatori abituarsi a scrivere documentazione, consiglio di prestare attenzione a quattro eccellenti strumenti che ora sono disponibili per quasi tutti.

Pagine GitHub

Probabilmente non c'è un solo sviluppatore oggi che non abbia esperienza di lavoro su GitHub. È anche un ottimo posto per i programmatori che hanno bisogno di un posto dove archiviare la documentazione. Molte persone utilizzano un file Readme standard nella propria base di codice per fornire all'utente una semplice guida pratica, ma questo non è l'unico modo per creare documentazione su GitHub. Con GitHub Pages , ottieni molto più che un semplice hosting per le pagine del tuo progetto, inclusi documentazione ed tutorial. Hai la possibilità di interagire direttamente con tutti i repository GitHub, consentendo agli sviluppatori di aggiornare la documentazione nello stesso modo in cui aggiornano il loro codice. Inoltre, puoi utilizzare Jekyll qui : ti aiuta a trasformare il tuo markup in testo semplice o in pagine web a tutti gli effetti.

Leggi i documenti

Come suggerisce il nome, Read the Docs fornisce agli sviluppatori una piattaforma per archiviare e leggere la documentazione. Il servizio funziona in modo molto simile a GitHub Pages: i programmatori possono apportare modifiche alla documentazione dai loro sistemi di controllo della versione preferiti, inclusi Git, Bazaar, Mercurial e altri. Sono supportati anche il controllo delle versioni automatico e la creazione di pagine. La parte migliore di Read Docs è la sua flessibilità. Supporta webhook in modo da poter automatizzare gran parte del processo di creazione del documento. Si tratta di un enorme risparmio di tempo su un'attività con cui la maggior parte dei programmatori non vuole avere nulla a che fare. Inoltre, tutto ciò che è ospitato sulla piattaforma è disponibile al grande pubblico in una varietà di formati, tra cui PDF, HTML a pagina singola e persino formato e-book. Il servizio si assume una parte significativa del lavoro di routine per mantenere aggiornata la documentazione.

Tetra

Tettra non è solo una piattaforma per archiviare la documentazione software, ma una base di conoscenza completa. Funziona particolarmente bene quando un progetto coinvolge un folto gruppo di programmatori che lavorano su diversi software. Tettra può essere utilizzato per documentare le risposte a domande comuni.

Apiario

Ciò che rende Apiary così utile per gli sviluppatori è il fatto che svolge un ottimo lavoro nell'aiutare con la documentazione API. La piattaforma consente agli utenti di scrivere la propria documentazione in Markdown , comprese le chiamate API fittizie. Apiary ti consente anche di testare e prototipare elementi API. In altre parole, è uno strumento di documentazione e una piattaforma di test in un unico posto.