Software Development

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.

Tony Hopkinson
Tony Hopkinson

.... You are going to use doc comments as the basis for your user documentation? Really?

dogknees
dogknees

If the comments do nothing but clutter up the code and provide no more information than is already obvious from the code, it is a negative when it comes to reading code. I just don't get the point of this sort of comments. When I inherit code, which is pretty common, I don't find these comments useful. On the contrary, they clutter up the code and make it more difficult to understand.

dogknees
dogknees

Are there any real-world examples of the comments it creates? In other words real production code with significant complexity. The examples they give look a bit contrived.

Tony Hopkinson
Tony Hopkinson

Good comments are produced by good developers, software tool is irrelevant.

TexasJetter
TexasJetter

Visual Studio will use the summary, param, returns, and remarks tags located at the top of a method/property/class to derive Intellisense when calling the code. So if you comment a method ???GetRecords??? you will see the comments as Intellisense when you type ???GetRecords(???

Justin James
Justin James

Visual Studio lets you collapse it, it doesn't clutter stuff up. J.Ja

zotwilliams
zotwilliams

Examples tend to look contrived because you want a few examples to show the range of results that are achieved. You should not expect these tools to completely document your code for you, but they will significantly reduce the time and work that you need to put in to create excellent documentation. Specifically, AtomineerUtils will: 1) Gather all available info it can from the code and summarise it in one place. This info is used in intellisense comments and external documentation, giving access to the docs in places where the source code is not available, or where it takes extra time and effort to find and read the source code to work out the details of how to use it. "Self documenting" code is a great start, but having the information instantly at your fingertips saves *so* *much* *time*. Using auto-complete on variable/type names doesn't write the code for you, it makes coding faster and easier. So why not use tools to write/update documentation fast as well?! 2) It tries hard to produce a human readable text description as a quality basis for your own documentation. With a stress on the word "basis" - you need to fill in those crucial extra details that other programmers need to understand to use/update your method correctly. 3) Where possible it re-uses documentation from base classes, overloads, properties and parameters elsewhere in your class. 4) It also constructs comments from a library of documentation, so well known cases are pre-defined and consistent. 5) It can add many useful things (optional entries for base classes/methods, author/date/time, etc) 6) It updates docs to ensure they are in sync with changes to the code 7) It ensures docs conform to a clear set of style guidelines 8) It applies word wrap, reformatting and controls whitespace to keep comments tidy and well formed, and can ensure the text is legal (e.g. converts characters like & < > into legal XML entities like & < >) If you try to do some or all of the above, you'll spend a lot of time documenting. Let the tools automate as much as they can so you can concentrate on describe all the additional things that cant be implied from self documenting code (such as whether a parameter can be null, what the return code is for an error condition, etc.) At the end of the day, there's a free trial - don't take my word for it, try it on your own code and see how well it does :-)

dogknees
dogknees

This article describes a tool that automatically generates comments. The developer isn't writing them. My question is where are the really clever tools that do more than pulling out the method signature and describing it in English. That is useless as far as I can see as your just duplicating information and cluttering up the code.

dogknees
dogknees

Are you talking about the comments that the product in this article create, or the ones Visual Studio creates automatically? I'm suspecting it's the later. I'm referring to those added by the documentation tool described in this article and it's relatives rather than the IDE.

zotwilliams
zotwilliams

It's not about wasting time writing incorrect or useless rubbish. Of course that's of no use. It's about making your code information rich and fast for a team to understand, use and maintain. Putting the crucial information in a doc comment significantly speeds up access to that information - a plot summary is always faster to read than the entire book (A parameter is sometimes easy to understand at a glance, but often you have to read an entire method quite carefully before you can work out what return values it will provide under what circumstances, or what exceptions it might throw. Or you may find it useful to follow a hyperlink to other relevant classes/methods that are not expressed in the code at all. Or you may just want to know quickly what the method is designed to achieve, not read carefully how it does it and then try to derive its intent from that. If you've never encountered these issues, then it's unlikely you've ever had to work in a team on a large/long-term project, working on complex code that you didn't personally write only a few days ago). These tools significantly speed up the process of providing good docs so you can gain from their many benefits without the cost in time/effort of having to meticulously construct and maintain them.

Justin James
Justin James

... is that they represent logic much more visually, and intent is MUCH easier to determine. Also, they allow metadata directly on the commands. For example, in Agile Platform, I drag a ForEach component on the screen, and when it lands on the screen, it says "ForEach" on it, but the title is highlighted with my cursor in it, for me to change it's name. That really encourages you to type "ForEach Invoice" or perhaps, just "Invoice" and let the symbol convey the "ForEach" aspect. When you see the logic laid out in a flowchart, intent is almost more clear. I'll put it this way... I've come back to extraordinarily complex pieces of logic months after I wrote them, and with under a minute's though, started making changes... in code that had zero "comments" as the system uses it. That's better than anything I ever got out of text-based comments, regardless of how in-sync or well written they were. J.Ja

Tony Hopkinson
Tony Hopkinson

even better if you could do some validation of meta data agaisnt code, flag them as out of sync etc. But as soon as you drop into unformatted english, we've still got the age old problem. I still firmly believe while we are commenting code instead of implementing intent at best we always be holding the brown end of the stick. Can't see the code for comments, is an issue I've run into many times, in every case the comments were useless, out of date, or just plain crap. I don't believe this is a coincidence.

dogknees
dogknees

1 - If the comments are of no value, which is what my position is, it doesn't matter how easy they are to maintain. 3 - Reading the code to determine the information these automatically generated comment include is significantly quicker and is always correct. A glance is enough to see the parameters, return type and the like. Or at least it is if you keep your code neat. 5 - Intellisense doesn't rely on these comments. It gets it's information directly from the code. I use it all the time. This is another reason the "structural" comments are of no value. If I want to see the list of members or the calling convention, Intellisense does that for me. Or an object browser.

Justin James
Justin James

They are complaining about comments littering the code. The answer is a metadata system where comments are appended to code. J.Ja

Tony Hopkinson
Tony Hopkinson

Totally and completely wrong! The code is How. Doc comments are What Annotation is Why. You've got the entire thing bass ackwards The requirement is to show Customer A's Invoices For that you need something that will return a list of invoices for customer. You need a set of unit tests that will prove that you can get 0,1 or many of something called invoice for something called customer that doesn't miss any. After that how is irrelevant is to what ever is calling the code. If it is then your code is crap, and no amounbt of dicumentation is ever going to make it better. Documenting after will always fail in a commercial environment, because once the code is deemed good enough, the resources required to go through and document it will disppear before you've run up the tool to do it. Developers let their comments get out synch, sheesh.

Tony Hopkinson
Tony Hopkinson

The best the tool can do is name and signature. int foo(int) What use is that? Comment : This function returns the square of the argument Better? Why didn't they call it Squared. What uses is when after getting the wrong result and you find it returns the cube? The tools, aid competent developers in competent environments, they don't substitute for one or both.

Justin James
Justin James

The utterly failed model of represented code with monolithic text files. Comments, in a superior system (OutSystem's Agile Platform, Alpha Software's Alpha Five, etc. etc. etc.) are META DATA both in use and in form, while in traditional, mainstream programming, comments are just text that is treated differently by the compiler and tools. J.Ja

zotwilliams
zotwilliams

1) This is not a magic fairy that does all your work for you, it is a tool for you to use to significantly speed up and improve the process of documenting code. It's a Resharper for docs rather than code. Do you complain that Resharper produces rubbish code? Or do you expect to have to do a little bit of the work yourself? 2) Without using a tool like this, programmers often let their comments get out of sync with the code, and *that* is when they become useless. The tool is therefore there to avoid "useless" comments. 3) A doc comment is a summary that brings together all the useful information from the code in a single place, in a standard and easy to read format. Why spend 2 minutes reading the code when you can read the summary in 10 seconds? 4) The programmer will augment the auto-generated documentation with all the critical info you need (can this parameter be null? Does index count from 0 or 1? what is returned to represent "not found"?). This information can often take a lot of reading of code to work out. 5) When you are calling a method, seeing intellisense pop up in a tooltip above your cursor is much faster than having to find the source code, read it, and then return. If you're not using intellisense, you're quite simply wasting a lot of time. 6) You won't always have easy access to the source code. 7) No, doc comments are not the basis of user documentation, unless your users are programmers and you are writing a library. Doc Comments are for describing how your code works to the programmers who have to maintain or call your code. 8) The act of writing doc comments makes you "describe your code to another person". Most people find that this process forces them to form a clear description of themethod, and thus gain a clear understanding of what they intend it to do. Just as unit tests make you think about the design, so do doc comments. The result is that you produce better quality, lower-defect code faster.

Tony Hopkinson
Tony Hopkinson

Expanded or not a useless comment just gets in the way. The problem isn't really the tools they can save you a bit of typing and apply a format for the comment so you can extract simple documentation, but without developer discipline, they are a total waste of space. Poor annotation is worse than no annotation. Always has been, always will be, and what these tools produce is poor, can't be anything else. The tools don't bother me, people who present them as press this button you have documentation, drive me wild.

Tony Hopkinson
Tony Hopkinson

I don't consider this generating comments. It's basically structuring a comment ready to be filled in, and then marking it up so some other thingy can differentiate them from ordinary annotation. In and of itself it's useless self defeating unmaintainable drivel, you need a good developer (better still a pair) to fill in the comments.

Editor's Picks