GhostDoc

15 August, 2007. 282 words.

I’ve been experimenting with GhostDoc for a while at work. I saw it mentioned somewhere on CodeBetter.com, and I figured if the cool kids were using it, it must be cool. At first I thought it was really cool to be able to drop comments into my source code with one click. I cheerfully starting doing “Document This” on every undocumented method, trying to get rid of those annoying “Missing XML comment for publicly visible type or member” warnings.

Then I started looking closer at the auto-generated comments I was making. If you don’t know, GhostDoc tries to parse out keywords from your method declaration signature to generate a human-readable comment. Here’s a typical example of what GhostDoc produces:

/// 
/// Notifies the specified trace.
/// 
/// if set to true [trace].
/// The FMT.
/// The args.
public static void Notify( bool trace, string fmt, params object[] args )
{
  if( trace ) Trace( fmt, args );
  WriteEventLog( fmt, args );
  SendMail( "Notification", fmt, args );
}

Well, okay, it’s got comments. But they are, shall we say, not helpful. You pretty much have to go back and replace everything that GhostDoc put in for you, or else future maintenance programmers will shake their heads in wonder at your complete lack of grammar skills, not to mention your inability to grasp what the code is really doing.

So I’m starting to think that GhostDoc is going to get the boot from my system. It’s a neat concept, but in reality it doesn’t save much time. In fact, I’m removing it right now. There.

Now I need to go back and rewrite all the comments that it put in for me. Sigh.

Related