Dove dovrebbe un programmatore spiegare la logica estesa dietro il codice?

Per quanto mi riguarda, più si avvicina la documentazione al codice, più è probabile che sia aggiornato e più utile sarà.

Ecco perché cerco di conservare tutta la documentazione nello stesso repository del codice, anche i manuali utente, e cerco di tenerlo in un formato di testo semplice che può essere facilmente gestito da un sistema di controllo di revisione.

Documentazione in-codice

Sembra che tu ne abbia già parlato, ma è importante ricordare che in realtà utilizza le funzionalità di documentazione nell'ambiente di sviluppo prescelto ( pydoc per python, javadoc in java o commenti XML in C #) è la tecnica di documentazione più importante. Semplificano 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, architettura, sviluppatore e possibilmente anche documentazione per l'utente finale. 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 è anche 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. 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.

Quando scrivo un codice altamente matematico, trovo anche utile avere alcuni wxmaxima documenti nel mio repository di progetti. Essendo di semplice testo, anche questi si diramano, si diff e si fondono bene, ma l'utilizzo di un sistema di algebra del computer può aiutarti a controllare la coerenza delle tue formule oltre a documentarli.

È possibile includere tale documentazione nei commenti XML e generare manuali LaTeX, pagine Web e altri documenti utilizzando doxygen . Utilizza gli elementi <remarks> e <example> per il prose esteso.

Vorrei utilizzare la documentazione esterna se è necessario includere diagrammi di classe, grafici, formule, immagini, ecc. per spiegare come funzionano le librerie. Includere questa documentazione esterna come parte delle versioni della libreria in qualsiasi formato si ritenga appropriato (LaTeX o altro). Puoi fare riferimento a questo documento dal tuo codice se lo desideri (ad es. "Vedi la documentazione" Leggimi "per maggiori informazioni.").

La chiave, credo, è coerenza . Se hai costantemente annotato i metodi con i commenti che possono essere estratti, ad es. Doxygen, ha senso includere anche la descrizione logica estesa, poiché è lì che è più probabile che gli altri sviluppatori guardino. Puntare all'improvviso lo sviluppatore su qualche altro documento sembra non necessario e confonderà solo gli sviluppatori.

Tuttavia, se la descrizione dell'intero programma è fornita altrove, dovresti rispettarla e fornire la descrizione logica estesa lì.

Se ritieni che sia necessario documentare l'interno di un metodo nella tua API, probabilmente non hai definito / modularizzato l'interfaccia molto bene.

Un'API ben scritta non dovrebbe RICHIEDERE al programmatore di capire come funzionano gli interni. Inoltre, documentando inutilmente il modo in cui funziona, si interrompe il livello di astrazione e si blocca in un'implementazione specifica, il che non è neanche positivo.