Doxygen, troppo pesante da mantenere?

Question

Attualmente sto iniziando a usare doxygen per documentare il mio codice sorgente. Ho notato che la sintassi è molto pesante, ogni volta che modifico il codice sorgente, devo anche cambiare il commento e ho davvero l'impressione di passare troppo tempo a modificare il commento per ogni modifica apportata al codice sorgente.

Avete alcuni suggerimenti per documentare il mio codice sorgente in modo efficiente?

Alcuni editor (o plug-in per l'editor esistente) per doxygen esistono le seguenti?

• traccia automaticamente codice/commento non sincronizzato e avvisa il programmatore.
• aggiungere automaticamente Doxygen commento formato (modello con il nome del parametro in esso per esempio) nel codice sorgente (template) per ogni nuovo elemento

PS: Sto lavorando su un progetto C/C++.

Answer 1

È la sintassi di Doxygen che si trova difficile? O è il fatto che devi commentare tutte le funzioni ora.

Se è il primo, potrebbe esserci uno strumento diverso che si adatta meglio allo stile di codifica. Tieni presente che Doxygen supporta più stili di commento, quindi prova a sperimentare finché non ne trovi uno che ti piace.

Se è il secondo, poi duro fuori. Come una buona pratica di programmazione, ogni funzione pubblica rivolta a dovrebbe avere un commento di intestazione che spiega:

1. ciò che la funzione fa
2. I parametri
3. i codici di ritorno
4. eventuali avvisi importanti/limitazioni circa la funzione.

Questo è vero indipendentemente dallo strumento di documentazione che si utilizza.

Il mio grande suggerimento: Evitare la tentazione di commentare troppo. Descrivi ciò che ti serve, e non di più. Doxygen ti offre molti tag, ma non devi usarli tutti.

• Non è sempre necessario un @ brief e una descrizione dettagliata.
• Non è necessario inserire il nome della funzione nei commenti.
• Non è necessario commentare la funzione prototipo E implementazione.
• Non è necessario il nome del file nella parte superiore di ogni file.
• Non è necessaria una cronologia delle versioni nei commenti. (Stai utilizzando uno strumento di controllo della versione, vero?)
• Non hai bisogno di una "ultima modifica data" o simile.

Per quanto riguarda la tua domanda: Doxygen ha alcune opzioni di configurazione per innescare avvisi quando i commenti che non corrispondono il codice. È possibile integrare questo nel processo di creazione e scansionare l'output di Doxygen per eventuali avvisi. Questo è il modo migliore che ho trovato per rilevare le deviazioni nel codice rispetto ai commenti.

Answer 2

Mi sembra che tu ritorni a quello che metti nei commenti, 5 minuti che commentano una lezione bene sarà tra 3 mesi quando la classe deve essere cambiata da qualcun altro oltre all'autore originale (anzi a volte dall'autore originale) prenditi molto meno tempo per fare i conti con.

In secondo luogo, il supporto alla documentazione menzionato da David, in eclissi quando si rifatta i nomi dei parametri, rinominerà il parametro nella sezione dei documenti, ad esempio. Non sono sicuro che vorrei che facesse qualcos'altro automaticamente per essere onesti.

"Ogni volta che modifico il codice sorgente, devo anche cambiare il commento" Potrebbe essere che stai documentando troppo. Dovresti solo cambiare la documentazione di una funzione se la modifica ad essa richiede di cambiare ogni chiamante in qualche modo (o se in realtà non cambia, almeno controllare per assicurarsi che non si basino su un comportamento obsoleto), di se stai introducendo nuove funzionalità su cui un nuovo chiamante farà affidamento. Quindi in teoria non dovrebbe essere un sovraccarico enorme. Piccole modifiche, come ottimizzazioni e correzioni di bug all'interno della funzione, di solito non hanno bisogno di documentazione.

Answer 3

Utilizzare commenti non di documentazione per le nuove funzionalità e le prime fasi del codice. Quando trovi che il tuo codice è pronto per la pubblicazione, puoi aggiornare i documenti. Evita anche la ripetizione di argomenti o nomi di funzioni.

Answer 4

Dipende molto dalla quantità di informazioni inserite nella documentazione.

Le mie funzioni sono generalmente più piccole ora a causa del test dell'unità e quindi la documentazione è corrispondentemente piccola. Inoltre, documentando la classe stessa, ho sempre un piccolo frammento di codice per mostrare come si suppone che la classe usi. Trovo che quelli sono i più difficili da mantenere, ma ne vale la pena, quindi non farti disturbare da juniors chiedendoti come usano la classe.

Punte:

• documento solo le interfacce pubbliche.
• Solo fare una documentazione minima su ciò che fa la funzione.
• Prova ad utilizzare un editor che supporti (la maggior parte lo fa) o ha un plugin.

Sarai felice quando verrai a modificare il tuo codice tra 6 mesi ...

Answer 5

C'è seriamente qualcosa di sbagliato nel modo in cui usi i commenti o come sviluppi.

I commenti Doxygen sono utilizzati per la documentazione esterna/interna sulle interfacce. Se le tue interfacce cambiano molto velocemente, probabilmente dovresti sederti e pensare prima al layout dell'architettura.

Se si utilizza doxygen per documentare il flusso interno delle funzioni, è possibile che si debba riconsiderare questo approccio (e anche in questo caso, questi commenti non dovrebbero cambiare molto). Quando hai una funzione che calcola un valore, allora un commento /// Calculating xy using the abc algorithm è sicuramente qualcosa che non dovrebbe cambiare ogni giorno.

Answer 6

Non esattamente quello che stai cercando ma questo Vim plugin può generare stub Doxygen oltre alle tue definizioni. Funziona piuttosto bene.

Answer 7

Nella mia esperienza software professionale, ogni volta che viene modificato un file sorgente, è necessario inserire un commento che descriva il cambiamento.Questi commenti di modifica solitamente non si trovano nelle aree di commento di Doxygen (a meno che non vengano apportate modifiche a un'interfaccia).

Ti consiglio caldamente di commentare il tuo codice come un'abitudine. Non solo è utile quando altre persone devono mantenerti o assistirti con il tuo codice, ma aiuta quando abbandoni un file sorgente per un po '(come quando la gestione ti dice di cambiare progetto). Ho trovato che scrivere commenti come codice mi aiuta a capire meglio gli algoritmi.

Answer 8

Giudicate voi stessi se lo stile sottostante soddisfa le vostre esigenze. È C-affine tho, ma forse puoi trarne abbastanza per i tuoi fini.

///\file 

/// Brief description goes here 
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
    /// @retval 1 will not do so for parameters. (see below) 
PLL_start( 
    unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the 
          ///  comment will go also. \n 
          /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n 
          /// 2-32767: whatever 
    int param)    ///< 0: crash \n 
          /// 1: boom \n 
          /// 2: bang! 
{ 
    /** 
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS! 
    * - Explain in list form. 
    * - It really helps the maintainer to grok the code faster. 
    * 
    *@attention Explain misuses which aren't caught at runtime. 
    * 
    *@pre Context: 
    * - This function expects only a small stack ... 
    * - The call is either blocking or non-blocking. No access to global data. 
    * 
    *@post The Foobar Interrupt is enabled. Used system resources: 
    * - FOO registers 
    * - BAR interrupts 
    */ 
    /**@post This is another postcondition. */ 
} 

Answer 9

Oltre a Doxygen penso che si dovrebbe dare un'occhiata a Code Rocket.

In realtà documenta cosa sta succedendo "dentro" i propri metodi trascinandoli attraverso il codice effettivo e i commenti che contengono, quindi non limitandosi solo alle intestazioni dei commenti delle funzioni, che possono non essere più aggiornate con i contenuti della funzione.

Fornirà automaticamente visualizzazioni di diagrammi di flusso e pseudocodice dei contenuti del metodo come forma di documentazione.

Answer 10

Utilizza i punti di forza di Doxygen: genererà descrizioni di classi e metodi senza aggiungere commenti (solo non di default: imposta EXTRACT_ALL = YES).

Non documento tutti i parametri perché penso che i loro nomi dovrebbero farlo per loro (*).

Sono contrario ai plugin di auto-documentazione che molte persone raccomandano perché creano commenti generici che dovranno quindi mantenere.

Desidero che i commenti siano significativi - se vedo un commento spicca e presterò attenzione.

(*) l'eccezione è quando le interfacce nel codice pubblico sono molto stabili e alcune persone trarranno beneficio da ulteriori spiegazioni, anche allora cerco di evitare la documentazione.