Linking in code comments (to other unique anchors/comments)

Question

How would you recommend creating "anchors" in code comments, so that during maintenance, developers can easily cross-reference other code comments.

I realise that software should be intelligently structured and this should mitigate this requirement to some degree, but I have often found myself writing a comment where I would like future developers to take something else into account (not necessarily a direct dependency).

For example, "If you change this mechanism, be sure to review XYZ". I'm thinking of hyper links, wiki-style, where each link has a unique identifier and can have a one-to-many relationship with other links.

Ideally, if someone re-writes some of my code, I would like them to be automatically warned that "something else links here, and you should check it out in case you're changing this" - and I don't mean breaking something as in "something won't compile", but really just an easy-to-follow pointer (or pointers) to somewhere else in a code base that someone (or indeed your past self) felt there was a human-understandable conceptual link, concept or implementation.

I would be surprised if there isn't already a standard in place for this, but searching for "comment", "link", "anchor" understandably yields a proverbial haystack.

Answer 1

There's no language-agnostic way of dealing with this problem: the solution is very much tied to your method of consumption of this information and what your language and tools can natively support.

If your language and IDE has a way to create and links to code elements (like C# XML Doc Comments or Java Doc), you can associate your documentation with a relevant code element and then link to that element from the other locations which are related to this. This might be good enough as the basis for a knowledge-base to consume through your IDE. You can probably extract this meta-information and build reference documentation that could be easier to consume.

If your IDE doesn't support this sort of linking, or you don't want to consume this information through your IDE, you'll need to go to something external, at which point a Wiki is the easy solution. A hyperlink to an article can be represented in any source file and anything starting http:// is easily followed by any developer.

Answer 2

If you're working in Java, you can create hyperlinks in the Javadoc, though I don't know of any IDEs that take advantage of this as opposed to parsing the code to determine what classes are linked together. See the documentation} for details, and this recommendation for when not to use them.

Answer 3

C# already implements XML Documentation Comments - some of the elements allow you to reference other types and depending on how you produce the documentation they will be links.

Answer 4

Visual Studio 2008, but not 2010, had a nice addin called HyperAddin for this purpose. Basically you would write #anchor in a comment, and elsewhere use code:#anchor to create a link to that comment. It also supported automatic word wrap in comments, and other little features.

Answer 5

What you are looking for is regression testing. No amount of comments will prevent a bug if no one reads them. But they are more likely to run into a test failure, especially with any sort of CI process.

Regression tests often appear trivial when written. But they ensure things don't break in the future. They aren't for you today, they are for you tomorrow.

If you are duplicating logic in two places, and they should be kept in sync, then considering refactoring the logic into shared code.