Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
2  
Some IDEs languages support this kind of thing natively. What platform/language/IDE are you specifically concerned with? –  Oded May 15 '12 at 10:28
    
C#, Visual Studio 2010 with ReSharper. –  TurtleDuck May 15 '12 at 15:50
add comment

4 Answers

up vote 0 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
And I'm guessing that a development team could therefore have a policy in place whereby a team member wishing to change or delete a class or class member should be performing a search for comments/documentation that mention the relevant item using these "strongly-typed" links. However, for more lengthy discussions on design decisions already taken, I suppose you could use the 'remarks' bit for outgoing links to a wiki article. I would personally use a wiki for my ultimate solution then (hyperlinks that aren't class- or member-specific). –  TurtleDuck May 15 '12 at 17:10
    
As far as I can tell, Visual Studio 2010 has no built-in ability to follow <see cref="..."/> links in those comments. –  Qwertie May 15 '12 at 18:27
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.