Commenti di codice a duplice scopo (utenti e manutentori) ... COME?

Question

Sto scrivendo una libreria statica C++ e ho commentato con i commenti doxygen nei file di implementazione. Non ho mai dovuto preoccuparmi molto della documentazione, ma sto lavorando a qualcosa che deve essere documentato bene per gli utenti e sto anche cercando di sostituire la mia precedente cattiva abitudine di voler solo codificare e non documentare con una migliore ingegneria del software pratiche.

In ogni caso, ho capito l'altro giorno che ho bisogno di un paio di tipi diversi di documentazione, un tipo per gli utenti della libreria (doxygen manual) e quindi commenti per me stesso o un futuro manutentore che si occupa maggiormente dei dettagli di implementazione.

Una delle mie soluzioni consiste nel mettere i commenti doxygen per file, classi e metodi nella parte inferiore del file di implementazione. Lì sarebbero fuori strada e potrei includere commenti normali dentro/intorno alle definizioni dei metodi a beneficio di un programmatore. So che è più lavoro, ma mi sembra il modo migliore per ottenere i due diversi tipi di commenti/documentazione. Sei d'accordo o hai qualche soluzione/principio che potrebbe essere utile. Ho guardato il sito ma non sono riuscito a trovare alcun thread che lo riguardasse.

Inoltre, non voglio davvero sporcare il file dell'interfaccia con i commenti perché ritengo sia meglio lasciare che l'interfaccia parli da sola. Preferirei che il manuale fosse il posto che un utente può vedere se ha bisogno di una comprensione più profonda dell'interfaccia della libreria. Sono sulla strada giusta qui?

Qualsiasi pensiero o commento è molto apprezzato.

modifica: Grazie a tutti per i vostri commenti. Ho imparato molto dal sentirli. Penso di avere una migliore comprensione di come separare il mio manuale utente dai commenti del codice che saranno utili a un maintainer. Mi piace l'idea che @jalf abbia un manuale in stile "prosa" che spiega come utilizzare la libreria. Penso davvero che sia meglio di un semplice manuale di riferimento. Detto questo ... Mi sento anche come se il manuale di riferimento potesse tornare utile. Penso che unirò il suo consiglio con i pensieri degli altri e cercherò di creare un ibrido. (Un manuale in prosa (usando i tag doxygen come pagina, sezione, sottosezione) che rimanda al manuale di riferimento.) Un altro suggerimento che mi è piaciuto da @jalf era l'idea del codice che non aveva un intero manuale interlacciato. Posso evitarlo mettendo tutti i miei commenti doxygen nella parte inferiore del file di implementazione. Ciò lascia le intestazioni pulite e l'implementazione pulita per inserire commenti utili a chi mantiene l'implementazione. Vedremo se questo funziona nella realtà. Questi sono solo i miei pensieri su ciò che ho imparato finora. Non sono sicuro che il mio approccio funzionerà bene o addirittura sarà pratico. Solo il tempo lo dirà.

Answer 1

Generalmente ritengo che i commenti per gli utenti dovrebbero non essere in linea nel codice, come commenti di ossigeno o qualcosa del genere. Dovrebbe essere un documento separato, in forma di prosa. Come utente della libreria, non ho bisogno di, o voglio, sapere cosa significa ogni parametro per una funzione. Speriamo che sia ovvio. Devo sapere qual è la funzione . E ho bisogno di sapere perché lo fa e quando chiamarlo. E ho bisogno di sapere cosa si applicano le pre e postcondizioni. Quali ipotesi assume la funzione quando la chiamo e quali garanzie fornisce quando ritorna?

Gli utenti della biblioteca non hanno bisogno di commenti, hanno bisogno di documentazione.Descrivi come è strutturata la libreria e come funziona e come usarla, e fallo così al di fuori del codice, in un vero documento di testo.

Naturalmente, il codice può ancora contenere commenti rivolti ai manutentori, che spiegano perché l'implementazione si presenta come fa, o come funziona se non è ovvia. Ma la documentazione di cui l'utente della libreria ha bisogno non dovrebbe essere nel codice.

Answer 2

Penso che l'approccio migliore sia utilizzare Doxygen per i file di intestazione per descrivere (agli utenti) come utilizzare ogni classe/metodo e utilizzare i commenti all'interno dei file .cpp per descrivere i dettagli di implementazione.

Answer 3

Ben fatto, il commento di Doxygen può essere molto utile sia durante la lettura del codice che durante la lettura dell'HTML generato. Tutta la difficoltà sta nel Ben fatto.

Il mio approccio è la seguente:

• Per gli utenti di biblioteca, ho messo i commenti Doxygen nei file di intestazione per spiegare qual è lo scopo di tale funzione e come usarlo dettagliando tutti gli argomenti, valori restituiti e possibili effetti collaterali. Provo a formattarlo in modo tale che la documentazione generata sia un manuale di riferimento.

• Per i maintainer, inserisco i commenti di base (non Doxygen) nei file di implementazione ogni volta che il codice di auto-commento non è sufficiente.

Inoltre, scrivo un file speciale introduttivo (a parte il codice) in formato Doxygen per spiegare ai nuovi utenti di libray come utilizzare le varie funzioni della biblioteca, sotto forma di istruzioni per l'uso, che punti ai dettagli del manuale di riferimento. Questa intro appare come la prima pagina della documentazione generata da Doxygen.

Answer 4

Doxygen consente la creazione di due versioni della documentazione (una per utenti e una per "uso interno") tramite il comando \internal e l'opzione INTERNAL_DOCS. E 'anche possibile avere un grana più fine di controllo con sezioni condizionali (si veda il comando \if e l'opzione ENABLED_SECTIONS.)

come altri hanno già fatto notare, è anche utile per fornire agli utenti (e anche manutentori a volte) qualcosa ad un livello superiore rispetto ai commenti del codice rigorosamente. Doxygen può essere utilizzato anche per questo, con il \mainpage, \ pagina [sub [sub]] sezione e \ par comandi

Answer 5

vi consiglio di dare un'occhiata a questo articolo: http://www.literateprogramming.com/knuthweb.pdf

normalmente applicato quelli idee ai miei progetti (usando Doxygen). Aiuta anche a mantenere aggiornato il documento perché non è necessario lasciare l'IDE, quindi è possibile effettuare annotazioni durante la codifica e, in seguito, rivedere il documento pdf finale per vedere cosa deve essere aggiornato o più dettagliato.

Nella mia esperienza, Doxygen richiede un po 'di lavoro in modo che il pdf abbia un bell'aspetto, i grafici e le immagini in posizione, ecc. Ma una volta individuati i modi e acquisito i limiti dello strumento, il lavoro viene svolto abbastanza bene.

Il mio suggerimento, oltre a quello che Kyle Lutz ed Eric Malefant hanno già detto, è di mettere lunghe spiegazioni sulle classi correlate nel proprio file (io uso un file di intestazione per questo) e aggiungere riferimenti ad altre parti usando i tag Doxygen. Devi solo includere quelle intestazioni nel file di configurazione di Doxygen (usando la corrispondenza del modello). Ciò evita di ingombrare troppo le intestazioni.

Answer 6

Non c'è una risposta rapida, una buona documentazione è difficile.

io personalmente sento un modello a strati è la cosa migliore.

• documenti di alto livello in prosa. Immagini e video sono molto appropriati.
• doc di livello di riferimento dovrebbe Doxygen (ben fatto doxygen, non solo commenti fuori mano).
• documenti manutentore non dovrebbero apparire nella documentazione di riferimento, ma potrebbe ancora essere Doxygen come sottolinea di Éric.

Mi piace molto lo stile di documentazione utilizzato in RakNet. L'autore utilizza ampi commenti su Doxygen e fornisce uno reference manual generato. Fornisce anche alcuni plain html tutorials. Meglio di tutti fornisce video walk-throughs di alcune delle caratteristiche più complicate.

altro buon esempio è SFML. La qualità non è buona come RakNet ma è comunque molto buona. Fornisce una buona pagina panoramica nello doxygen generated documentation. Ci sono alcuni plain html tutorials e una semplice pagina di caratteristiche/panoramica in html.

preferisco questi stili come Doxygen generato documentazione è generalmente troppo basso livello quando sono appena agli inizi, ma perfettamente conciso una volta che sono nella scanalatura.