Metodologia per la documentazione della base di codice esistente

Lavoro come parte di un team su un'applicazione esistente che non ha documentazione in linea, né ha documentazione tecnica. Mentre stavo lavorando su varie segnalazioni di bug sull'applicazione, ho scritto una sorta di traccia di breadcrumb per me stesso: numeri di bug in vari punti in modo che il prossimo sviluppatore possa fare riferimento a quel numero di bug per vedere cosa stava succedendo.

La mia domanda è quindi:

Qual è il metodo più efficiente per documentare questo codice? Devo documentare mentre tocco l'area (il metodo del virus, se lo desideri) o dovrei documentare da ogni sezione per conto suo e non seguire percorsi che si diramano in altre aree dell'applicazione? Devo inserire commenti incorporati laddove non esistesse in precedenza (con la paura che potessi finire per identificare in modo errato cosa fa il codice)?

Quale metodo useresti per documentare in modo accurato e rapido un'applicazione piuttosto grande che non ha documentazione in linea esistente, né riferimenti in linea a documentazione esterna?

Documentazione di basi di codice legacy

Consiglio vivamente di seguire la regola dello scout di scouting con basi di codice legacy. Cercare di documentare un progetto legacy indipendentemente dal lavorare su di esso non accadrà mai.

Documentazione nel codice

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

Se fai affidamento sul tornare e documentare le cose in un secondo momento, potresti non aggirarlo, ma se lo fai mentre stai scrivendo il codice, 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 incompatibile con il codice effettivo.

Test come documentazione

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

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

Allo stesso modo, i test unitari spesso evidenziano esplicitamente dipendenze esterne attraverso le quali le cose devono essere simulate .

Trovo anche che usando lo sviluppo Test-driven scrivo software che è più facile da usare, perché lo sto usando fin dall'inizio. Con un buon framework di test, rendere il codice più facile da testare e renderlo facile da usare sono spesso la stessa cosa.

Documentazione di livello superiore

Infine c'è cosa fare a livello di sistema e documentazione architetturale. Molti raccomanderebbero di scrivere tale documentazione in un wiki o di utilizzare Word o altri elaboratori di testi, ma per me il posto migliore per tale documentazione è anche accanto al codice, in un formato di testo semplice che è compatibile con il controllo della versione.

Proprio come con la documentazione in-code, se memorizzi la tua documentazione di livello superiore nel tuo repository di codice, è più probabile che tu la tenga aggiornata. Inoltre, si ottiene il vantaggio che quando si estrae la versione XY del codice, si ottiene anche la versione XY della documentazione. Inoltre, se si utilizza un formato compatibile con VCS, significa che è facile ramificare, diffondere e unire, proprio come il codice.

Per prima cosa mi piace , poiché è facile produrre sia pagine html che documenti pdf da esso, ed è molto più amichevole di LaTeX , ma può ancora includere espressioni matematiche LaTeX quando ne hai bisogno.

Domanda ingannevole. Fondamentalmente, userei il metodo "refactoring", che ribadirei come "se tocchi il codice, documentalo".

Ma per essere precisi; quando sorgono problemi e quando 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 per correggere il bug a quel punto ti ha costretto a acquisire abbastanza familiarità con il codice per poterlo documentare. E per questo motivo, sarei diffidente nel seguire rami non correlati O nel 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 di capire esattamente cosa fa il codice e perché. (Non sto entrando 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 bug; tu '

Questo approccio dovrebbe tendere a massimizzare l'accuratezza, sacrificando la velocità complessiva, ma senza influire sulla necessità di mantenere il codice troppo severamente allo stesso tempo. Se i tuoi compiti di correzione di bug sono piccoli, ovviamente, puoi avventurarti in "territori sconosciuti" e iniziare a documentare lì, ma se tu (come la maggior parte di noi) non riesci a trovare abbastanza tempo nel giorno sia per correggere il codice che per documentarlo, questo è un buon compromesso.

Una cosa vale anche notare; dovresti avere una buona documentazione esterna. Dici che il tuo codice non ha riferimenti a documentazione esterna; Spero per il tuo bene che esista tale documentazione esterna. In caso contrario, farei in modo che scrivere quella documentazione esterna sia la tua prima priorità; qualcosa a livello di una specifica funzionale è, penso, assolutamente fondamentale per tutti i grandi progetti software. Il motivo è che le specifiche funzionali, o la documentazione di alto livello di quel modulo, possono aiutare a prevenire "scorrimento delle caratteristiche" o "deriva delle caratteristiche" in qualsiasi software; e la deriva delle caratteristiche (in particolare) può essere distruttiva per la documentazione in quanto può rendere obsoleta la documentazione. (Definisco il creep di funzionalità come l'aggiunta progressiva (e fastidiosa) di funzionalità a un software; deriva della funzioned'altra parte, è dove l'insieme di azioni che il software compie lentamente cambia nel tempo. Il creep di funzionalità è ADDITIVO, cioè di solito comporta un aumento del set di funzionalità del software; la deriva delle caratteristiche, d'altra parte, è somma zero; uno per uno, un pezzo di funzionalità edge viene definito per fare qualcosa di diverso, fino a quando il software non fa qualcosa di completamente diverso da quello originariamente previsto. La deriva delle funzioni è rara, ma DEADLY per la documentazione.)

Un'applicazione che ho co-sviluppato nel corso di due anni aveva una grave mancanza di documentazione. A un certo punto è diventato chiaro che passeremo l'applicazione a un altro sviluppatore che l'avrebbe mantenuta da quel momento in poi, quindi abbiamo dovuto documentare il codice.

Per gestire l'enorme portata del processo di documentazione, proverei a documentare tutto il codice in una specifica funzionalità o parte dell'app in un determinato giorno. Non avevo un modello particolare, ma un'insistenza nel fare alcuni ogni giorno e 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 nel programma del progetto ed ha evitato molto del tedio che accompagna la documentazione.

Abbiamo usato la documentazione XML in C # e ci ha fornito funzionalità e strutture sufficienti per semplificare la documentazione. Anche se non stai documentando un'app C #, lo schema di avere un breve riepilogo seguito da osservazioni è stato molto usfeul.

Vorrei documentare come ho aggiunto / modificato il codice. A parte questo, documenterei anche le API pubbliche o eventuali interfacce tra i moduli. Se dovessi documentare tutto il codice, potresti non visualizzare il ROI per il tempo impiegato. Può essere utile usare qualcosa come una wiki per organizzare la documentazione esterna mentre la sviluppi. Il documento più utile a cui ho fatto riferimento quando ho iniziato il mio ultimo progetto era il documento di architettura. Comprendeva informazioni sulle tecnologie utilizzate e forniva una visione di alto livello su come l'applicazione era stratificata.

Vorrei usare i commenti Doxygen. Doxygen ha più formati di output rispetto alla maggior parte degli altri formati gratuiti ed è semplice da imparare.

Potresti anche prendere in considerazione l'assunzione di un appaltatore per farlo, poiché 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 sviluppatore alla documentazione del codice. Quindi fai in modo che ogni nuova persona lo attraversi mentre si alzano alla velocità. Ricorda che alcuni sviluppatori considerano questo come ottenere un canale radicolare, necessario solo nei casi diretti, LOL.

Prima di iniziare a documentare qualsiasi cosa, sviluppare uno standard. Questo può essere semplice come assicurarsi di scrivere alcune righe sopra una funzione o un'intestazione di classe su qualcosa di più ufficiale e dettagliato (come javadoc). Prima che chiunque possa effettuare il check-in del codice, la sua documentazione deve soddisfare tale standard.

Quello che ho trovato funziona bene è l'aggiunta di commenti ben scritti prima dell'intestazione della funzione alle funzioni che avevo creato in precedenza non documentate e l'aggiunta di commenti in linea a tutto ciò che ho aggiunto. Vuoi evitare di documentare il codice che non hai toccato. È peggio avere commenti negativi piuttosto che nessun commento, e se lo stai documentando "rapidamente", probabilmente scriverai commenti negativi.