Developer's should comment their code more. However I have noticed that comments alone are not enough. You need to be able to FIND the relevant comments at the time you need them. It is reasonably common that related pieces of code are lexically far from on another so you might not find the comments you are interested in at the time you need them. One manifestation of this is that there is often no good place to put an 'overview' comment so that readers can find it. The first step in encouraging people to write good comments in their code is to increase the value of those comments by 'channeling' people who should be reading it to comments most relevant to them.
This is where the Visual Studio HyperAddin comes in. Visual Studio already had the ability to recognize and quickly navigate (with Ctrl LeftClick) to URLs embedded in the comments of the code. This is great, but what is really needed is a way of referring quickly and easily from one part of the code to part of the code (or to architectural documents checked in with the code). That is exactly what the HyperAddin does: It makes creating and following hyper-links in your code trivial. Now you only have to explain something once in a comment and refer to it many times (got lots of overloaded methods? They should all refer to the 'master' that does the real work).
Another related feature is the 'GoOut' command that takes you to the enclosing structure (either method, class, or file). These are great places to put 'overview' comments and cross links to other subsystems. With a few such links you get a richly interconnected graph of comments that let people navigate to where they want (kind of like the web).
The other feature of HyperAddin is related to comments too. When you start writing comments that are many lines long, you find that what you really want your editor to word wrap. The HyperAddin does this for you too. But even that is not enough. You want your comments to be more like a word processor, with bulleted lists, and smart indenting. While we can't make a ASCII file into a full fledged word processor, Hyperlink does its best with a few simple conventions.
In short the HyperAddin tries to take some of the pain out of writing more comments for your code.
The main features of the HyperAddin are
These features manifest themselves in two user interface elements
See the Install/Uninstall section below.
Visual Studio already had support for embedding web links (eg http://www.msn.com) in the comments of code. You follow a hyperlink by pressing the Ctrl' key and pressing the left mouse button. This is already very useful for allowing you to references to algorithms (think wikipedia), specifications, or anything else that had a URL. However it is also very useful to embed links from one portion of the code to another. The HyperAddin add this capability by adding code: URLs. .
// In this comment I wanted to talk about the code:MethodTable::Unbox method. // By Adding a code: hyperlink, readers can quickly navigate to it. Any name // that can be found using the Edit.FindSymbol (Alt-F12) can be used. If you // need to refer to an overloaded method, it is best to use an anchor (see below).
// #mytopic
//
// ...
// Somewhere else in the file you can refer to code:#mytopic. Now readers
// can quickly navigate to the #mytopic anchor.
// I need to refer to #mytopic but it is not in the current file. But I
// know that this anchor is related to the class 'MethodTable' and thus will
// be in the same file as that class definition by using code:MethodTable#mytopic
// I can refer to #mytopic anywhere in any code within the solution.
There is an obvious problem if you have overloaded method names. The question is 'which one does the code: hyperlink go to? The answer is 'the first one'. Effectively it is arbitrary. Now often this is not an issue because all the different instances of the overloaded methods are semantically very similar and tend to call one another, so a few F12 (goto definition) will allow the user to navigate to the one that does the real work. However when you need to refer to a specific instance you can use the # anchors to go to a very specific overload.
The code: hyperlinks a simple but powerful feature for making your code much more readable. Sometimes, however you want to create a diagram, or using formatting that is very inconvenient to create with simple text. For that the obvious solution is to create the document in some other tool (say Word, or OneNote), and then refer to it using a hyperlink in your code. Unfortunately, in Visual Studio the file: URL does not work for relative file paths, so the HyperAddin fixed this. For example:
// I created a very nice block diagram quickly and easily using Viso, and saved // The file as 'classDiagram.vsd' in the same directory as this current file. // I can refer to it by file:.\classDiagram.vsd and allow readers to quickly open it. // As in HTML, relative paths are relative to the file that made the reference.
// The file: url also works with # anchors for text(source) files. For example if you // use by file:.\someSourceFile.cs#myTopic and allow you to refer to the #myTopic // anchor in someSourceFile.cs. If you are certain that you will not move the // #myTopic anchor out of this file, and that the file will always stay in the // same relative place, you can use this way of referring to it. Generally however // it is better to use code: anchors for this because the # anchors move with the // data structure they describe.
Code hyperlinks significantly help readers find comments and related code that will help them understand the code they are reading. However they do require that the writer have the forethought to write the code: hyperlinks. The 'Go Out' command is an attempt to do useful navigation without requiring explicit hyperlinks. The basic idea, is that when a reader is reading code, there are three natural places for the writer of the code to put 'big picture' comments.
The 'Go Out' command (Ctrl+Comma), supports this navigating to these places quckly.
This functionality gives you a very simple procedure to find useful comments. Simply hit (Ctrl+,) one or more times. Obviously this is only useful if the writer of code put good comments at these locations. Note that the Ctrl+- (Ctrl+Minus) is useful for getting back to where you where after you have used the Go Out command
A code base should have a 'table of contents'. The natural place for this is the top of the file that has the Main() method (because GoOut on Main() will naturally go there). The table of contents should have an anchor #TableOfContents, and there should be a code:#TableOfContents link at the top of the Main() method that leads to it. The table of contents' main purpose is to provide a set of links to the other main parts of the program. This is usually best done by writing a paragraph or so about the program as a whole, and the major components, and having an outline that lists the hyperlinks to the code for the major components.
In general it is useful if the major components of the application are richly interconnected with hyperlinks. Usually they should have a back link to the table of contents, and any related components. This makes it easy to navigate to related code quickly. If there are any specifications associated with the program as a whole or any of its pieces, the of course should be linked using file: URL hyperlinks.
File: URLs are particular useful if you want to put diagrams into your code. Just use a diagram editor of your choice that generates output compatible with Internet Explorer, check it in alongside the code, and use file: URL to refer to it. Readers will then be able to conveniently access the diagrams from Visual Studio.
You want to make the 'Go Out' command as useful as possible, by putting a hyperlink at the top of a file or a class that will link back to the table of contents. This way, by simply using the 'Go Out' command anywhere in the code base, a reader can find the table of contents, and then navigate from there.
Hyperlinks are also very useful during development itself. It is useful for class comments to have links to the most important methods, and this mini table of contents has the added advantage that it makes navigating to these 'hot spots' quick an easy (Go Out -> Go Out -> Click on Hyperlink). Think of them as 'permanent' named bookmarks. Thus put them in early, and use them during development.
The #region and #endregion declarations in C# are very handy for grouping your comments into logical sections. These allow comments to be collapsed as a individual groups (by default all comments that are not separated by code are collapsed as a single group when outlining (Ctrl-M Ctrl-O) is activated.
Hyperlinks and the 'Go Out' command are all about making it easy for readers to find useful comments. This is only helpful, however if writers actually write the comments (or more commonly, readers add comments after having to puzzle out how a piece of code works). Word Wrapping is all about making it easy to write comments. The basic idea, is that you don't need a word processor to write reasonably looking comments. You can write very good looking comments with just word wrapping and auto-indenting so that you can make paragraphs and bulleted lists.
By default when the HyperAddin is installed it enables word wrapping and auto-indenting inside // style comments. What this means is that if you start a // comment and just keep typing, when the word wrap margin is hit, the IDE will automatically start a new line, // chars, and indentation to continue the line. By default the margin is 110 characters, but you can change it by selecting the 'Set Word Wrap' item on the 'Addin' menu. If you find the word wrapping annoying, you can turn it off with the 'Disable Word Wrap' item on the 'Addin' menu. These settings are persisted (in the file HyperAddin.dll.config file), so after setting your preference here it will persist from session to session.
If you hit a newline in a comment block, the IDE assumes that you are continuing the comment, and thus inserts the // and indentation necessary for that scenario. This can be annoying if you just wanted to create a one line // comment. If you hit a return and did NOT want to continue the comment hit Ctrl+Z (undo), and it will remove the comment characters. If you hit Ctrl+Z again, it removes all indentation, and if you Ctrl+Z again, it undoes the newline.
While the 'on the fly' wrapping is useful for creating new comments, when you modify existing comments, the word wrapping gets ruined, and needs to be fixed. This is what the 'Format Comment' (Alt+C Alt+F) button on the HyperAddin toolbar does. Basically it word wraps the entire paragraph using the following rules to distinguish paragraphs.
These rules are relatively simple, but allow quite a bit of flexibility in your comments. * makes for bulleted lists, and <> characters support XML style comments (eg. if you program in C#).
By default the 'Format Comment' command will format the entire comment block that the cursor is in. However if a block of text is selected, it will only format lines in that selecti
on. Moreover the formatting rules work whether or not the lines begin with // or not. Thus you can format /* */ style comments by selecting the body of the comment and hitting 'Format Comment'. You can even word wrap plain text files by reading them into the IDE, selecting all text and hitting 'Format Comment'.
The HyperAddin allows user defined commands to be added to the HyperAddin menu bar. While Visual Studio also has this same capability (on the Tools Menu), it is often convinient to package the external tools with the Addin, rather than Visual Studio. To add new user defined commands you update the HyperAddin.dll.config file. For example
Defines a command called 'EchoSolution' which has a shorcut of typeing Alt+E twice, and prints out the solution path to the Addin log. Once you add a new command to the file, you have to tell Visual Studio that it should update its IDE to display it. You do this with the following command
This tells Visual Studioto ask HyperAddin to redo its GUI from scratch (and the new commands will show up).
As can be seen in the 'EchoSolution example, the syntax $(variableName) in the command line to execute denotes variables that will be substituted at the time the command is invoked. The following variables are currently defined.
If you have problems with HyperAddin, you can turn on logging to help understand the issue. When logging is turned on messages are sent to the output window (Ctrl-W O) in a 'Addin Log' pane. It should come up automatically so it should be obvious. Whether logging is on or off is also persisted in the HyperAddin.dll.config file so you can diagnose startup problems too.
To install HyperAddin simply copy all the HyperLink* files from the distribution point to your Visual Studio Addins directory. For example
If you wish to uninstall HyperAddin.