Metodologia per documentare la base di codice esistente

Documentazione di basi di codice legacy

Raccomando vivamente di seguire la regola boy-scout con basi di codice legacy. Cercare di documentare un progetto legacy indipendentemente dal lavoro su di esso non accadrà mai.

Documentazione in-codice

La cosa più importante è usare le strutture di documentazione nell'ambiente di sviluppo prescelto, quindi significa pydoc per python, javadoc in java o commenti XML in C #. Ciò semplifica la scrittura della documentazione contemporaneamente alla scrittura del codice.

Se ti affidi a tornare indietro ea documentare le cose in un secondo momento, potresti non farcela, ma se lo fai mentre stai scrivendo il codice, allora ciò che deve essere documentato sarà fresco nella tua mente. C # ha anche la possibilità di emettere un avviso di compilazione se la documentazione XML è incompleta o incoerente con il codice effettivo.

Test come documentazione

Un altro aspetto importante è avere una buona integrazione e test unitari.

Spesso la documentazione si concentra su ciò che le classi e i metodi fanno isolatamente, ignorando il modo in cui vengono utilizzati insieme per risolvere il problema. I test spesso li mettono in contesto mostrando come interagiscono tra loro.

Allo stesso modo, i test unitari spesso indicano le dipendenze esterne in modo esplicito attraverso le quali le cose devono essere Mock ed eliminate.

Trovo anche che usando Sviluppo guidato dai test scrivo software che è più facile da usare, perché io usandolo fin dall'inizio. Con un buon framework di testing, rendere il codice più facile da testare e renderlo facile da usare spesso è la stessa cosa.

Documentazione di livello superiore

Infine c'è da fare su livello di sistema e documentazione architettonica. Molti sostengono di scrivere tale documentazione in un wiki o usando Word o altri elaboratori di testi, ma per me il posto migliore per tale documentazione è accanto al codice, in un formato di testo semplice che è adatto al controllo di versione.

Proprio come con la documentazione in codice, se si archivia la documentazione di livello superiore nel proprio repository di codice, è più probabile che si mantenga aggiornato. Hai anche il vantaggio che quando estrai la versione X.Y del codice, ottieni anche la versione X.Y della documentazione. Inoltre, se utilizzi un formato VCS friendly, significa che è facile diramare, diff e unire, proprio come il tuo codice.

Mi piace molto rst , dal momento che è facile produrre sia pagine html che documenti pdf da esso, ed è molto più amichevole di LaTeX , ma può ancora includere espressioni matematiche Lattice quando ne hai bisogno.

Domanda spinosa. Fondamentalmente, userei il metodo "refactoring", che vorrei riformulare come "se tocchi il codice, documentalo".

Ma per essere precisi; man mano che sorgono problemi, e dato che devi acquisire familiarità con il codice per correggere i bug che si verificano, direi che dovresti usare quella familiarità per scrivere commenti su quel codice in particolare; in sostanza, la motivazione a correggere il bug ha obbligato a guadagnare abbastanza familiarità con il codice per poterlo documentare. E per questo motivo, sarei dispiaciuto di seguire filiali non correlate O di documentare funzioni non correlate, perché a quel punto, se non stai eseguendo test attivi del codice (per verificare la tua correzione di bug), allora è difficile essere totalmente certo che capisci esattamente cosa fa il codice e perché. (Non mi sto addentrando nel problema che può anche essere difficile capire esattamente cosa e perché il codice fa quello che fa anche quando si verifica una correzione di un bug, probabilmente lo hai capito dalle tue esperienze.)

Questo approccio dovrebbe tendere a massimizzare l'accuratezza, con un sacrificio della velocità generale, ma senza influire sulla necessità di mantenere il codice troppo severamente allo stesso tempo. Se i tuoi doveri di correzione del bug sono piccoli, puoi avventurarti in "territorio sconosciuto" e iniziare a documentare lì, ma se tu (come la maggior parte di noi) non trovi abbastanza tempo al giorno per risolvere il problema e documentarlo, questo è un buon compromesso.

Una cosa vale anche la pena; dovresti avere una buona documentazione esterna. Tu dici che il tuo codice non ha riferimenti a documentazione esterna; Spero per il tuo bene che tale documentazione esterna esista, però. Altrimenti, in realtà scriverei che la documentazione esterna è la tua prima priorità; Penso che qualcosa al livello di una specifica funzionale sia assolutamente critico per tutti i grandi progetti di software. La ragione è che le specifiche funzionali, o la documentazione di alto livello di quel modulo, possono aiutare a prevenire "strisciamento di funzionalità" o "spostamento di funzionalità" in qualsiasi software; e la deriva delle caratteristiche (in particolare) può essere distruttiva per la documentazione in quanto può causare l'aggiornamento della documentazione. (Definisco la caratteristica creep come progressiva (e fastidiosa) aggiunta di funzionalità a un software, la funzione deriva , d'altra parte, è dove l'insieme di azioni che il software prende lentamente cambia nel tempo. Feature creep è ADDITIVE, cioè di solito comporta l'aumento della serie di funzionalità del software, mentre la deriva delle caratteristiche, d'altra parte, è a somma zero, una alla volta, una funzionalità di bordo viene definita per fare qualcosa di diverso, fino a quando il software sta facendo qualcosa di completamente diverso da quello previsto inizialmente. La deriva delle caratteristiche è rara, ma MORTALE per la documentazione.)

Un'applicazione che ho sviluppato congiuntamente nel corso di due anni ha avuto una grave mancanza di documentazione. Ad un certo punto è diventato chiaro che abbiamo passato l'applicazione a un altro sviluppatore che avrebbe dovuto mantenerlo da quel momento in avanti, quindi abbiamo dovuto documentare il codice.

Per affrontare il gigantesco ambito del processo di documentazione, proverei a documentare tutto il codice in una specifica funzione o parte dell'app in un dato giorno. Non avevo uno schema particolare, ma un'insistenza a fare un po 'ogni giorno, e ad ottenere un senso di completamento documentando un intero file o una sezione dell'app ogni giorno.

Ci sono voluti mesi per documentare l'intera applicazione, ma a mezz'ora (max) al giorno non ha mai veramente mangiato il programma del progetto ed evitato gran parte del tedio che accompagna la documentazione.

Abbiamo usato la documentazione XML in C #, e ha fornito abbastanza caratteristiche e strutture per rendere facile la documentazione. Anche se non stai documentando un'app C #, il modello di avere un breve riassunto prima seguito da commenti è stato molto utile.

Vorrei documentare come ho aggiunto / modificato il codice. Oltre a questo, documenterei anche le API pubbliche o qualsiasi interfaccia tra i moduli. Se dovessi documentare tutto il codice potresti non vedere il ROI per il tempo speso. Potrebbe essere utile usare qualcosa come una wiki per organizzare la documentazione esterna man mano che la sviluppi. Il documento più utile a cui ho fatto riferimento quando ho iniziato il mio ultimo progetto è stato il documento di architettura. Includeva informazioni sulle tecnologie utilizzate e forniva una vista di alto livello su come l'applicazione era stratificata.

Userei i commenti di Doxygen. Doxygen ha più formati di output che la maggior parte degli altri formati gratuiti ed è semplice da imparare.

Potresti anche prendere in considerazione l'assunzione di un appaltatore per farlo, dato che alcuni di noi lo fanno per vivere. Tuttavia, con questa scelta devi ancora impegnarti a rivedere i documenti.

Un'altra tecnica comune è quella di assegnare il nuovo dev per documentare il codice. Poi fai in modo che ogni nuova persona la segua mentre si alza. Siate consapevoli del fatto che alcuni sviluppatori considerano questo come un canale radicolare - necessario solo nei casi diretti, LOL.

Prima di iniziare a documentare qualsiasi cosa, sviluppa uno standard. Questo può essere tanto semplice quanto assicurarti di scrivere poche righe sopra una funzione o un'intestazione di classe in qualcosa di più ufficiale e dettagliato (come javadoc). Prima che chiunque possa effettuare il check-in del codice, la loro documentazione deve soddisfare lo standard.

Ciò che ho trovato funziona bene è l'aggiunta di commenti ben scritti prima dell'intestazione della funzione alle funzioni che ho creato che erano precedentemente non documentate e l'aggiunta di commenti incorporati a tutto ciò che ho aggiunto. Vuoi evitare di documentare il codice che non hai toccato. È peggio avere commenti negativi che non commenti, e se stai documentando questo 'velocemente', probabilmente scriverai commenti negativi.