C'è un modo per commentare un file sorgente usando un file separato?

Di quali commenti stai parlando?

In genere trovi 4 tipi di commenti nel codice sorgente:

1. Commenti generali sul "manufatto" (ad esempio scopo, paternità, licenza, contenuto del file, cronologia delle versioni, ecc.), spesso inseriti all'inizio del file;
2. Documentazione dei commenti della struttura di implementazione e dell'API (ad esempio, ogni classe e funzione);
3. Suggerimenti utili su particolari scelte di implementazione o trucchi usati nel codice che sarebbe difficile capire dalla lettura del codice.
4. Logorrea ridondante inutile (commenti allo scopo di inserire un commento, ad esempio: if (c.isEmpty()) // if c is empty

I commenti 1 e 2 potrebbero facilmente essere inseriti in file di documentazione separati:

• Il vantaggio di averli nella sorgente è una pura comodità di prossimità: se si modifica la struttura di una classe o il comportamento di una funzione, è più semplice aggiornare la documentazione direttamente nel file sorgente. Viceversa se manca una documentazione, tutti lo noteranno.
• Ma l'inconveniente è la lettura o la navigazione di documenti sparsi su molti file. Questo è il motivo per cui strumenti di documentazione come Doxygen sono così popolari per la generazione di documentazione in formato HTML o di testo.
• Inoltre, se manterrai un modello UML, parte della documentazione del codice sorgente sarebbe ridondante con la documentazione del modello.

Commenti 3 non possono essere n un file separato. Per lo più indicano alcuni aspetti specifici di un gruppo di dichiarazioni molto preciso nel codice. Il loro significato verrebbe perso se tu li estraessi, separandoli dal loro codice (esempio: //don't increment anymore or it would go out of bound non ti direbbe nulla se non vedi dove era e quale variabile era in gioco!).

Potresti eliminare i commenti 4, in particolare con codice pulito (ss le belle citazioni di RCMartin sul commento ) . Sfortunatamente è difficile distinguerli da 3.

Come ottenere la transizione

È sempre un processo doloroso. Ma potresti optare per alcuni strumenti:

• potresti aggiornare leggermente i tuoi commenti, in modo da generare con doxygen un file di documentazione e quindi mantenere questo file. A proposito, se segui questo percorso e rivedi / unisci il codice, puoi anche optare per un approccio darwinistico: modifica i commenti che vuoi mantenere per averli in doxygen
• potresti utilizzare un parser di commenti esistente come questo .
• potresti creare il tuo strumento, basato su questo esempio (da migliorare), e implementare un meccanismo di conteggio delle coppie che riconoscerebbe i commenti che sono al di fuori di un blocco e li copia / li sposta in un file di documentazione (suggerimento: fai attenzione ai blocchi dei nomi)

Questo sembra essere un problema impossibile, per definizione.

Supponiamo che tu avessi un set di file .txt , uno per ciascun file .cpp , contenente i tuoi commenti, separati per ciascuna funzione, naturalmente.

Quindi, quando si scarica una versione più recente del pacchetto, si dovrà comunque affrontare (a) i file sorgente rinominati e (b) le funzioni rinominate all'interno dei file sorgente, per non menzionare (c) i dettagli modificati all'interno di tali funzioni. Quindi avresti ancora lo stesso problema di fusione che hai ora.

Fondamentalmente, i tuoi commenti dipendono dal codice sorgente ovunque li memorizzi: se in /*…*/ all'interno del codice sorgente o al di fuori di esso, in un file di testo con tag ordinato con lo stesso nome del file sorgente. Dovrai sempre riunire nuovamente ogni aggiornamento .

Detto questo, costruisci alcuni strumenti .

1. A filleter , che accetta i file di origine con commenti extra che hai, scrive i commenti su un file di testo o su più file di testo o su un database, rilevando quale funzione e file ciascuno il commento appartiene a e rimuove tali commenti dal file sorgente originale. Quest'ultimo aspetto è importante, perché in questo modo puoi guardare il file sorgente da solo per vedere se qualcuno dei tuoi commenti è stato lasciato indietro e sintonizzare e riscrivi il filleter fino a quando non ha veramente riempito tutto.

2. Un stuffer , che accetta un file sorgente senza commenti aggiuntivi e il / i file / database di testo creati dal filleter e inserisce i commenti nel file sorgente nell'appropriato posto. Se non riesce a trovare dove inserire un commento, allora si supera in un modo o nell'altro e ti lascia fare quel pezzo di lavoro a mano.

Puoi facilmente testare il stuffer filettando il codice sorgente che hai ottenuto e poi riempendolo. Se quello che ottieni è ciò che hai iniziato, funziona tutto.

Oltre alle altre risposte, potresti prendere in considerazione alcuni approccio di programmazione alfabetica . Quindi, i tuoi file sorgente: i file che digiterai nel tuo editor, ad es. emacs - potrebbe essere un codice di miscelazione markup specializzato e frammenti di documentazione, e dovrai usare uno strumento per generare il codice (riordinerà correttamente i frammenti di codice per produrre un file C ++) e un altro strumento per generare la documentazione (compresi alcuni "commenti strutturati"), forse con alcuni riferimenti incrociati.

Una volta ho codificato un garbage collector (proprietario) utilizzando un approccio LP. Ho una sensazione mista. È molto buono per le parti dell'interfaccia (l'API), ma forse troppo "verboso" per i dettagli di implementazione. YMMV.

Ovviamente, è meglio usare LP all'inizio del progetto. Trascorrerai molto tempo per convertire correttamente alcuni codici esistenti in LP.

^{(Immagino che tu stia usando una grande libreria di software libero)}

BTW, per seguire una grande base di software libero, dovresti affidarti alla sua comunità di sviluppatori: chiedi sulla mailing list o sulle pertinenti domande architettoniche del wiki. Forse contribuire, almeno alcune note di documentazione. In altre parole, non aspettarti soluzioni tecniche a un problema non tecnico (ma sociale: un grande software libero è basato principalmente sulla sua comunità e la sua architettura sta cambiando).