Riferimenti incrociati nei commenti del codice sorgente

Question

A volte quando si scrive un programma è necessario fare riferimento a un'altra parte/o funzione nei commenti. Ad esempio nel codice seguente potrei impostare due ancore "workaround1" e "workaround2" (in un altro file) nei commenti e prendere nota della funzione ABC con riferimenti ai commenti pertinenti.

// this part does <<workaround1>> 
a = 1; 
a++; 
... 

// [[workaround1]] and [[file:c.java::workaround2][2]] can be removed once ABC is fixed 
c = ABC(); 

Ho due domande:

1. C'è best practice per tali riferimenti? Come si occupano i programmatori professionisti?
2. Esiste un pacchetto per emacs che può facilitare la navigazione attraverso un codice sorgente di commenti con tali note? Stavo pensando all'estensione org-mode con la possibilità di lavorare su (preferibilmente qualsiasi) modalità linguistica.

Sono consapevole circa la domanda simile su Redmine: Can I create a cross-project source reference in redmine?

Answer 1

Non ci sono senza dubbio diversi approcci disponibili. Qualcuno probabilmente descriverà come usare org-mode per questo, che è forse l'approccio più comune. Personalmente, io uso linkd.el - semplice. Puoi ottenerlo here.

Lo uso nei file Emacs-Lisp, ma è possibile utilizzarlo in qualsiasi file di testo.

Un colpo di testa, o la destinazione di nome assomiglia a questo testo come semplice:

 
     ;; (@* "Common helper functions") 

Questo è per Lisp, dove ; inizia un commento. Nel tuo caso, dovresti usare //, credo.

un link ad esso dallo stesso file è simile al seguente:

 
     ;; (@> "Common helper functions") 

un link ad esso da un file diverso aspetto:

 
     ;; (@file :file-name "foo.el" :to "Common helper functions") 

Ma sono reso usando evidenziando, e senza i caratteri estranei.

Una destinazione si presenta così (ma evidenziato):

collegamento

 
     * Common helper functions 

Uno stesso file si presenta così (ma ha sottolineato come un collegamento Emacs, e con mouseover evidenziazione):

 
     > Common helper functions 

Un collegamento a file diversi è simile a questo (ma evidenziato come collegamento, con mouseover):

 
     . foo.el : Common helper functions