Developer

Jump-start code comments with GhostDoc

GhostDoc is a Visual Studio 2010 add-on that makes creating useful comments as easy as a few button or mouse clicks.

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! Figure A
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.

Inserting comments

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.

Wish list

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.

About

Tony Patton has worn many hats over his 15+ years in the IT industry while witnessing many technologies come and go. He currently focuses on .NET and Web Development while trying to grasp the many facets of supporting such technologies in a productio...

25 comments
deshan.baptiste
deshan.baptiste

I happen to like well commented code. I like explicit header information. I have tried both Ghost Docs and the Atomineer product and like both, but I like Atomineer's product better; however, since my employer (at my last job where I used them) wouldn't pay for it, i settled on the free option provided by Ghost Doc. It's been awhile since I've used them, but I thought they did help intellisense by providing documentation for your method parameters and return types (maybe that's just in my head?). If it does, who want's to use "go to definition" just to figure out what the exact purpose of each parameter is? Maybe you, but not me... I work with people who have named parameters "p" or "_p", so the more information they are forced to provide through updated comments the better for someone who maintains their code...yes it's preferable to have self documenting code with expressive naming, but that's not always the case and when you inherit poorly written code, it is helpful to have slightly modified comments and the easier it is to produce these comments, the better the chance that they will actually be written. I give it a +1.

zotwilliams
zotwilliams

... don't waste their time doing things that the computer can automate. Do you use intellisense to auto-complete your variable/type names? If so, what is different about using a tool to save you lots of time in documenting? Of course the tool does not *do* the entire job for you, any more than intellisense will write the code for you. But it helps you do the job better and faster. You will always need to add information to complete the documentation, but these tools save you so much time getting started and keeping the code and docs in sync. (Typical users save $2000-$3000 worth of programmer minutes per year)

zotwilliams
zotwilliams

Rather than waiting indefinitely for the features you've suggested to be implemented in GhostDoc, why not check out AtomineerUtils Pro Documentation, which already does everything GD does and much, much more (including documenting exceptions thrown within a method). It supports XML, JavaDoc, Qt and Doxygen comments, and works for C#, C++/CLI, C++, C, Java and Visual Basic. It can word wrap your comments and has many options to completely control the style and layout of the comment blocks. For a feature comparison with GhostDoc and other add-ins, see: http://www.atomineerutils.com/compare.php

dogknees
dogknees

It looks like all the comments are simply re-stating the function definitions in English. Since that information is obvious to a programmer, I don't really see the point of this sort of comment. I know it's common practice for some to fill their code with this sort of duplicated information, but I find it just makes it harder to see the logic of the code. It's like the standard Java doco pages. A bland listing of member functions and objects is useless without details of how it is used and what the functions actually accomplish. I've seen something similar in an associates code. He leaves the previous non-functional code as a comment when he modifies it. So you end up with 80% of the code being junk that you have to try and wade through to find the real code. Now, if the vendors would bring some truly modern AI technology to bare on the problem, I'm sure we could start seeing auto-generated comments that actually describe the algorithm that the code implements. All it needs is for the vendors to apply the same sort of resources to development tools as they throw at their Office Productivity suites.

jim.lonero
jim.lonero

I used to use GhostDoc, but I found this new tool by Atomineer that makes the comments look much better (good for production code). This documenting package also documents you source file and works with C++ and C code (as well as C#). It is also available via the Tools dropdown menu within the Visual Studio IDE At the start of the file (line 1), I can have Atomineer add the following comment: //////////////////////////////////////////////////////////////////////////////////////////////////// // project: DragAndDropOfImage // file: DragAndDropOfImage\Form1.cs // // summary: Implements the form 1 class // // Copyright (c) 2011 My Coompany Inc. All rights reserved. //////////////////////////////////////////////////////////////////////////////////////////////////// using System; using System.Drawing; using System.Windows.Forms; The class level documenting is as such: namespace DragAndDropOfImage { //////////////////////////////////////////////////////////////////////////////////////////////////// /// Form 1. /// /// My Developer Name, 11/22/2011. //////////////////////////////////////////////////////////////////////////////////////////////////// public partial class Form1 : Form {...} And, each function as: //////////////////////////////////////////////////////////////////////////////////////////////////// /// Event handler. Called by panel for drag enter events. /// /// . /// /// Source of the event. /// Drag event information. //////////////////////////////////////////////////////////////////////////////////////////////////// private void panel_DragEnter(object sender, DragEventArgs e) {...} There are many more functions available that I haven't yet explored. The help is quite complete and useful. Also, you can set how your comments are formed in a configuration file (see the help about this). And, there is an options setup dialog where you can further make changes in the settings. For more information, go to http://www.atomineerutils.com.

Editor's Picks