C++: dove scrivere la documentazione del codice: in .cpp o in file .hpp?

Question

Dove è usuale scrivere la documentazione in codice di classi e metodi?

Si scrivono tali blocchi di documenti sopra la classe/metodo corrispondente nel file di intestazione (.hpp) o nel file di origine (.cpp)?

Esiste una convenzione ampiamente rispettata per queste cose? La maggior parte dei progetti C++ lo fa in un modo piuttosto che nell'altro?

Oppure la documentazione deve essere scritta sui due lati (vale a dire nei file .hpp e .cpp), magari con una breve descrizione da una parte e una più lunga dall'altra parte?

Principalmente, esistono alcune considerazioni pratiche che rendono più conveniente scrivere in un modo piuttosto che nell'altro modo? (Ad esempio l'uso di parser e generatori di documentazione automatici come Doxygen ...)

Answer 1

Entrambi:

• Descrivere la progettazione e l'utilizzo di API nell'intestazione: questo è l'interfaccia pubblica per i clienti.
• Descrivi le alternative di implementazione/problemi e le decisioni nell'implementazione: questo è per te stesso - più tardi - e altri manutentori/promotori, anche qualcuno che rivede il design come input per alcuni anni del sistema next-gen da qui.

commento tutto ciò che non è ovvio, e niente che è (a meno che il vostro strumento di documentazione è troppo stupido per produrre una buona documentazione senza).

Evitare di inserire documenti di implementazione nelle intestazioni, in quanto la modifica dell'intestazione implica che i test del timestamp del makefile attiveranno una ricompilazione non necessaria per le app client che includono l'intestazione (almeno in un ambiente di libreria aziendale o commerciale). Per lo stesso motivo, mirare a mantenere la documentazione di intestazione stabile e utilizzabile - abbastanza buono da non dover continuare ad aggiornarlo come i clienti si lamentano o chiedono esempi.

Answer 2

Se si crea una libreria, si distribuisce in genere la libreria compilata ei file di intestazione. Ciò rende più utile mettere la documentazione nei file di intestazione.

Answer 3

Ancora, entrambi. Per quanto riguarda la documentazione pubblica, è bello essere in .h con un formato estraibile con Doxygen, ad esempio, come altri hanno commentato. Mi piace molto il modo Perl di documentare le cose. Il file .pl (o .pm) include la documentazione in sé che può essere estratta usando uno strumento simile a quello che Doxygen fa per il codice C++. Inoltre, Doxygen ti consente di creare diverse pagine che ti consentono di includere manuali utente, ecc., Non solo di documentare il codice sorgente o l'API. In genere mi piace l'idea di un file .h/.hpp autonomo nella filosofia della programmazione alfabetica.

Answer 4

Personalmente mi piace la documentazione nei file di intestazione. Tuttavia, alcuni ritengono che la documentazione debba essere inserita nei file sorgente. La ragione è che quando qualcosa cambia, la documentazione è proprio lì che ti ricorda di aggiornarlo. Sono un po 'd'accordo, come ho personalmente dimenticato di aggiornare i commenti Doxygen nell'intestazione quando ho cambiato qualcosa nei file di origine.

Continuo a preferire i commenti Doxygen nel file di intestazione per ragioni estetiche e le vecchie abitudini sono difficili da modificare. Ho provato entrambi e Doxygen offre la flessibilità di documentare nei file di origine o di intestazione.

Answer 5

Ancora più importante, ci sono considerazioni pratiche che lo rende più conveniente scrivere in un modo , piuttosto che il contrario?

Si supponga di voler aggiungere un chiarimento a uno dei commenti senza modificare il codice. Il problema è che il tuo sistema di build vedrà solo che hai cambiato il file e supporterà inutilmente che debba essere ricompilato.

Se i commenti sono nel file .cpp, verrà ricompilato solo un file. Se i commenti sono nel file .hpp, ricompilare ogni file .cpp che dipende da tale intestazione. Questa è una buona ragione per preferire avere i tuoi commenti nei file .cpp.

(ad esempio, la uso di parser documentazione automatica e generatori come Doxygen ...)

Doxygen consente di scrivere i vostri commenti in entrambi i casi.