bling.github.io

This blog has relocated to bling.github.io.

Thursday, March 10, 2011

That Commenting Thing

I’m working on a project right now that has near 99% of its code commented.  Wow, that’s impressive!  Actually, it’s more scary…even some of the private fields are commented….

At one point, someone decided that it was a good idea to impose some kind of standard rather than none, so they recommended StyleCop with all of its default settings, including requiring comments on everything.

This seemed like a good idea, and it probably was, until someone found GhostDoc.  The plugin definitely gives off that “cool” factor the first time you use it.  Wow, with a single key stroke it automagically documented all of my code!!!  The problem, and it’s a pretty big one, is that it generates documentation based on the name of the properties, names, and class.  Surely if it can do that, you, a much more sophisticated machine, can do that!

Alas, the code base ended up getting GhostDocced to death all over the place to the point where I was driven mad and insane that I spent the time to write a VS2010 extension to purposely hide these comments.  I’m talking about comments like this:

image

The comments add absolutely no value and IMO makes it harder to read, and has the added deficit that if for whatever reason someone changes the name property, chances are they will forget to update the comments.  It gets worse with WCF service contracts with many parameters.

So yes, it frustrated me enough that I took some spare time to write an extension to shrink those damn XML comments to such a small size it doesn’t bother me anymore, like this:

image

You can grab the code off GitHub.