When you’re working with existing application code, the chances of finding that code thoroughly documented are slim. Most developers aren’t too demanding — we just need a basic understanding of what an application is supposed to do when confronted with a method (even a quick sentence on what it does and information on its parameters) and away we go. The Visual Studio add-on GhostDoc provides the framework for code comments with a mouse-click or keystrokes.
GhostDoc works as advertised
I was apprehensive about the promise of GhostDoc. A colleague had been prodding me for quite some time to use it, but I remained resolute (stubborn?) and stuck with my old way of doing things (by hand). I was asked to work with an existing code base and to insert comments as a guide for other developers, so I finally gave in and installed GhostDoc to (hopefully) simplify the task at hand. Now I’m a fan of the tool.
The GhostDoc download comes in two flavors: Basic and Pro. GhostDoc Basic is free and provides the basic functionality of the tool, as you can easily insert comments in your code with a few clicks. GhostDoc Pro adds a few more features such as commenting a complete file with one click and automated comment blocks are configurable. GhostDoc Pro is used in the screenshots in this post, but the features covered are available in both versions.
At your fingertips
Once installed, GhostDoc is available via the Tools dropdown menu within the Visual Studio IDE. Figure A shows the menu as it appears with GhostDoc Pro installed. GhostDoc Basic will create the same menu with a few less options like Document File grayed out so it’s unavailable. In addition, a basic GhostDoc context menu is available by right-clicking your mouse when you’re in your source code. This allows you to document while coding — imagine that!
The GhostDoc menu within Visual Studio 2010
My favorite approach to commenting is via a predefined shortcut that is configured during installation. The [Ctrl][Shift][D] combination is the default, but you can choose what you like within reason as [Ctrl][Shift][Delete] is not available for obvious reasons. If you decide that you dislike the chosen key combination, you can change it via the GhostDoc menu via the Re-assign Shortcut selection as shown in Figure A. Also, you can “Run Configuration Wizard” to rerun the configuration wizard that runs when first installed.
An individual portion of code (method, property, class definition, etc.) can be commented by moving the cursor to its location within the source code and choosing Document This or by using your key combination. As an example, I commented an existing method in my code as the next snippet demonstrates:
/// <summary> /// Populates the team child nodes. /// </summary> /// <param name="curNode">The cur node.</param> /// <returns></returns> /// <remarks></remarks> public static System.Windows.Forms.TreeNode populateTeamChildNodes(System.Windows.Forms.TreeNode curNode)
The comment shows that it recognized its parameters and that it returns a value. In addition, it made a valiant effort to place text in the summary element by processing the method name — parsing the words and adding “the” so populateTeamChildNodes becomes “Populates the team child nodes.” Doing the same thing with a class declaration produces similar results:
/// <summary> /// Summary description for Class1. /// </summary> /// <remarks></remarks> public class Class1
It isn’t flashy, but that is the point of GhostDoc — it only writes XML comments. You can go through code and insert these comments individually or comment a complete file on the fly (only in the Pro version), but you’ll still need to update the comments.
Note: The comments generated by GhostDoc are not useful until you add text to the comments and any other pertinent details. Thus, GhostDoc doesn’t actually solve anything — it provides you with a framework for entering useful information in comments.
GhostDoc isn’t for everybody; the tool does a basic task, and it focuses on that without adding a lot of other features. One common complaint is the lack of support for generating an XML file or even HTML from the comments, but you can use a tool like Doxygen to create HTML output. I would like GhostDoc to add the return type in the returns comment element, as well as a list of exceptions raised in the comment block.
If there is something you truly want or need, post a comment on the GhostDoc discussion forum, as they seem to be very responsive.
Leave a trail
Commenting source code has been an issue since developers began building applications. Thankfully, GhostDoc makes creating useful comments as easy as a few button or mouse clicks.
There a plenty of great Visual Studio add-ins available today for documentation, as well as many more tasks. What tools do you prefer in your daily coding? Share your recommendations and thoughts with the TechRepublic community.