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 funzionalità di documentazione nell'ambiente di sviluppo scelto, 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 in modo esplicito le dipendenze esterne 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 sul livello di sistema e sulla 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 è il controllo della versione del sistema amichevole.
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. Ottieni 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.