Quali sono i buoni modi per documentare il software scientifico?

Molte volte, quando ho ereditato o incontrato codice scientifico scritto da altre persone (o occasionalmente, anche il mio lavoro), ho notato che la documentazione è scarsa o inesistente. Se sono fortunato, vedo commenti informativi. Se sono molto fortunato, ci sono anche commenti Doxygen e un Doxyfile in modo da avere interfacce funzionali e un po 'di HTML formattato da consultare. Se sono estremamente fortunato, c'è un manuale PDF ed esempi oltre ai commenti su Doxygen e sul file sorgente, e sono estatico, perché mi rende la vita molto, molto più semplice.

Quali informazioni e strumenti sono utili nella documentazione del codice sorgente? Del resto, quali informazioni e strumenti sono utili per documentare i dati e i risultati che accompagnano quel codice sorgente, nel caso del software scientifico?

Penso che la documentazione per il software scientifico possa essere suddivisa in tre categorie, tutte necessarie per la piena comprensione. La più semplice e comune è la documentazione del metodo individuale. Ci sono molti sistemi per questo. Tu dici doxygen , Python ha pydoc e in PETSc abbiamo la nostra semina del pacchetto che genera quanto segue .

Tuttavia, per qualsiasi software che vada oltre una semplice utility, è necessario un manuale. Ciò fornisce una visione di alto livello dello scopo del pacchetto e di come le sue diverse funzionalità si integrano per raggiungere questo scopo. Aiuta un nuovo utente a strutturare il proprio codice, spesso attraverso l'uso di esempi. In PETSc, utilizziamo LaTeX per il manuale, ma il pacchetto PyClaw utilizza il framework Sphinx di cui sono rimasto molto colpito. Una cosa che abbiamo implementato nel pacchetto di semina che trovo molto utile è il collegamento tra il codice di esempio e la documentazione della funzione. Ad esempio, questo esempiorisolve l'equazione di Bratu. Si noti come è possibile seguire i collegamenti per qualsiasi tipo personalizzato o chiamata di funzione e accedere alla documentazione di basso livello e come tali pagine rimandano agli esempi che li utilizzano. Ecco come apprendo nuove funzionalità a cui contribuiscono altre persone nel progetto.

Una parte della documentazione spesso trascurata, penso, è la documentazione per gli sviluppatori. Non è raro pubblicare un documento in stile codifica e le istruzioni per interagire con il repository. Tuttavia, è molto raro spiegare le decisioni di progettazione prese prima dell'implementazione. Queste decisioni comportano sempre compromessi e la situazione relativa all'hardware e agli algoritmi cambierà necessariamente nel tempo. Senza una discussione dei compromessi esaminati e delle motivazioni per particolari decisioni di progettazione, i programmatori successivi sono lasciati a ricreare l'intero processo da soli. Penso che questo sia un grave ostacolo alla corretta manutenzione e al miglioramento dei vecchi codici quando gli sviluppatori originali non sono più responsabili.

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 architettonica. Molti raccomanderebbero di scrivere tale documentazione in un wiki o di usare 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 è 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 la documentazione, proprio come il codice.

Mi piace abbastanza reStructuredText (primo) , poiché è facile produrre pagine html e documenti pdf da esso usando la sfinge , ed è molto più amichevole di LaTeX , ma può ancora includere espressioni matematiche LaTeX quando ne hai bisogno.

Prenderò obiezioni su quasi tutti i punti sollevati da Faheem . In particolare:

1 / "Penso che non sia realistico aspettarsi che gli sviluppatori scientifici trascorrano molto tempo a documentare il loro software". Questa è una prescrizione per un progetto fallito che presto nessuno sarà in grado di usare chi non ha accesso agli sviluppatori primari. È per una buona ragione che le grandi biblioteche informatiche scientifiche (ad es. PETSc o deal.II) dispongono di un'ampia documentazione che arriva a migliaia di pagine o più. Non è possibile avere una comunità di utenti considerevole se non si dispone di un'ampia documentazione. Concordo, tuttavia, che i codici di esempio devono essere semplici e focalizzati su un unico concetto.

2 / "gli autori dovrebbero prendere in considerazione l'idea di scrivere un documento per la pubblicazione, se del caso". Questo spesso non è possibile in pratica. Si possono scrivere articoli su concetti e algoritmi, ma non sull'interfaccia e su altre decisioni di progettazione. I lettori di tali articoli avranno un'idea di ciò che l'implementazione fa; gli utenti dell'implementazione dovranno sapere quali funzioni chiamare, cosa significano gli argomenti, ecc. Come utente, il più delle volte si può vivere senza il primo e semplicemente considerare una libreria come una scatola nera, ma non si può fare a meno informazioni sull'interfaccia.

Questa è una buona domanda Per una prima approssimazione, il codice dovrebbe tentare di auto documentare. Quindi, ad esempio, se il software è a riga di comando, dovresti essere in grado di fare executable --helpo executable -ho addirittura executable(se l'eseguibile non fa nulla senza argomenti) e avere un breve messaggio di ritorno sull'utilizzo.

Secondo, penso che non sia realistico aspettarsi che gli sviluppatori scientifici trascorrano molto tempo a documentare il loro software, quindi suggerisco di mantenerlo semplice. Un breve manuale di testo con i metodi e le opzioni di base e funzionamento annotato e testatoesempi di utilizzo, che vanno da semplici a più complessi (gli esempi di utilizzo sono molto importanti e spesso trascurati) è considerevolmente migliore di niente e molto di più della maggior parte dei software scientifici offerti. Vorrei anche aggiungere una pipì per animali domestici sugli esempi di utilizzo. Semplice significa semplice. Ciò significa che se stai cercando di illustrare un metodo, non aggiungi dieci concetti o metodi estranei per confondere il lettore. Mantenerlo semplice e annotare in modo che il lettore sappia cosa dovrebbe fare l'esempio. Suggerirei anche di collegare gli esempi di utilizzo manuale in una suite di test in modo che continuino a funzionare quando il codice viene modificato. In realtà non so come farlo in un modo carino, quindi sentitevi liberi di educarmi. Se gli sviluppatori vogliono essere più fantasiosi, sicuri di poter usare simpatici linguaggi di markup e così via, aggiungere pagine man e così via.

In terzo luogo, gli autori dovrebbero considerare la possibilità di scrivere un documento per la pubblicazione, se del caso. Questo di solito affronta le decisioni di progettazione e fornisce una prospettiva di livello più elevato sul software rispetto a un manuale, o ci si può aspettare che faccia. Questo verrebbe indirizzato alla documentazione delle decisioni di progettazione di cui parlava @Matt.

Naturalmente, la documentazione più importante di tutte è il codice stesso, che dovrebbe essere commentato se necessario. Ciò presuppone che il codice sia un software libero. In caso contrario, è sostanzialmente meno utile come software scientifico (vuoi davvero usare una scatola nera in cui non puoi vedere come sono implementati i metodi?) E io per primo non lo userei.

Per rispondere alla tua domanda su come documentare dati e risultati, consiglierei qualcosa come il modulo doctest di Python . Ciò consente di scrivere tutorial o test in un modo che può essere validato automaticamente.

Se sei interessato alla programmazione alfabetica, dai un'occhiata a org-babel . Fa parte della modalità org in Emacs e offre quindi una vasta gamma di opzioni di esportazione (LaTeX, PDF, HTML, ODT) per la documentazione. Emacs può visualizzare immagini all'interno del buffer e consentire di scrivere equazioni matematiche nella sintassi LaTeX in modo da non doversi limitare alla semplice documentazione di testo.

La documentazione derivata automaticamente dal codice sorgente è un componente essenziale per avere una documentazione aggiornata, ad es. Corretta. Non riesco a contare quante volte ho visto la documentazione che è indietro di anni rispetto al codice sorgente a causa dell'apatia degli sviluppatori verso la documentazione. La soluzione semplice è quella di rendere più facile per i programmatori scrivere la documentazione insieme al nuovo codice nello stesso posto allo stesso tempo, piuttosto che come uno sforzo a posteriori che sarà inevitabilmente prioritario a favore di attività più gloriose.

Se costretto a scegliere, preferirei avere commenti dettagliati e precisi (cioè attuali) sul codice sorgente, ma nessun manuale per l'utente che un manuale per l'utente obsoleto pieno di informazioni sbagliate.

In Python ci sono gli strumenti pep8 e pep257 che riporteranno documentazione mancante o non valida. elpy per Emacs si lamenterà anche della documentazione mancante. Le convenzioni di Docstring di Numpy con reStructuredText sono buone da seguire. Il test con pep8, pep257 e doctest può essere configurato con py.test e tox eseguiti automaticamente.