Writing approachable code: Introducing the hyperaddin for Visual Studio!

A few years ago now, several of us on the .NET Runtime team where lamenting how unapproachable the code base was for new developers to the team.    We agreed that more commenting would certainly help the situation, but that alone was not enough, because you also need to FIND the comments WHEN they are relevent for the comments to actually be useful.   Typically the most useful comments are not about a particular line of code, but information about the purpose of a whole method, class, or subsystem, and what the global invarients are.   Finding these very useful comments is often not a trivial exercise. 

It occured to us at the time that this problem is not so different from finding relevent data on internet, and that having hyperlinks would help alot to 'channel' people to important relevant comments.  This was the genesis of the HyperAddin.   The idea is that Visual Studio already supported having hyperlinks in comments (any strings starting with https:// becomes a link that you can Ctrl-left click on).    The idea is to add a new string called code: identifier  which turns into a hyperlink that looks up the definition to identifier.  Now it is possible for one part of the code base to refer to another by symbolic name.   

Taking our cue from HTML, we added the capability of sub-file anchors.  Any comment of the form

  • // #SomeIdentifier

Defines an anchor in that file called SomeIdentifier.  You can then refer to it by the hyperlink code: identifier#tag.   Like HTML, this is a hyperlink to code: identifier (which gets you to the correct file) followed by a search on that 'page' (file) for 'tag'.  The result is that it is now trivial for one comment to refer to another.  

With this simple change, it is now possible to write a very nice overview comment and refer to it in dozens of places.  Having used it for several months now, I find it very constraining on those occasions that I am not writing code in visual studio, and thus do not have my code hyperlinks.    In retrospect I am amazed that someone did not think of this earlier (which is a hallmark of a good idea).

There is more to say about what the hyperaddin can do for you (stay tuned), but this blog entry is mostly about getting you to try it.   Just today I published the addin on codePlex as HyperAddin.  Please click on the link and follow the installation instructions (it is an XCOPY deployment).    If you use Visual Studio, give it a try right now.

If you like the capabilities of HyperAddin and wish that Visual Studio had this feature, you can vote on this here.  To vote, click on the 'Sign in to Rate' (and register if necessary), and then click on the number of stars in the rating box that corresponds to the value of this feature.   The more people who vote, the more likely this feature is to get into Visual Studio.