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.

2 comments:

Vsevolod Parfenov said...

Why don't you fold them instead of changing font size?

bling said...

Originally I tried to use code folding to solve the problem, but the best thing that comes built-in is collapsing to definitions (Ctrl+M/O), which will fold everything. But that also folds the methods as well, so then I'd have to manually unfold them, which quickly got tiresome.

The optimal solution I think would be for the extension to automatically collapse only the comments when you open a file, but that is much more complex than just changing the font size....maybe an exercise for another weekend when I'm bored with nothing to do...