Cross references in source code comments

Question

Sometimes when you write a program you need to refer to another part/or function in the comments. For example in the code below I could set two anchors "workaround1" and "workaround2" (in another file) in the comments, and make a note about ABC function with references to the relevant comments.

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

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

I have two questions:

1. Is there best practice for such references? How professional programmers deal with it?
2. Is there a package for emacs which can facilitate navigation through a source code comments with such notes? I was thinking about org-mode extension with can work on top of (preferably any) language mode.

I'm aware about similar question on Redmine: Can I create a cross-project source reference in redmine?

Answer 1

There are no doubt different approaches available. Someone will likely describe how to use org-mode for this, which is perhaps the most common approach. Personally, I use linkd.el -- simple. You can get it here.

I use it in Emacs-Lisp files, but you can use it in any text file.

A header, or named destination looks like this as plain text:

      ;; (@* "Common helper functions")

That's for Lisp, where ; begins a comment. In your case, you would use //, I believe.

A link to it from the same file looks like this:

      ;; (@> "Common helper functions")

A link to it from a different file looks like this:

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

But they are rendered using highlighting, and without the extraneous chars.

A destination looks like this (but highlighted):

      * Common helper functions

A same-file link looks like this (but highlighted as an Emacs link, and with mouseover highlighting):

      > Common helper functions

A different-file link looks like this (but highlighted as a link, with mouseover):

      . foo.el : Common helper functions