Generated by a tool, not for human consumption

A few years ago I had an interesting discussion with some of my then coworkers about the XML comments in our code. XML comments were useful in some cases because we were writing some libraries to be shared with many of our applications. We kept the DLLs, the XML and the CHM all in the build folder for any other developer that needed to use that library.

I know some of you have strong opinions against or in favor of XML comments. What I know is that they don't bother me but I'd trade them for a clear and self-explanatory API in a heartbeat.

But what really bothered me was when one of the guys came to me and showed this amazing Visual Studio add-on that would automatically generate the XML comments for him. I won't name the tool here because it's not important. GhostDoc (ooopsy!!!) goes through all your code, finds where XML comments can be put, and tries to guess the text of the comment from the name of the members, parameters, etc. When it finishes, a method named GetOrders will have a description "Gets the orders", a property or parameter named UserName will become "Gets the name of the user", and so on. See image below as an example.

Now, let's think about this for a second. Suppose you are trying to use a class that has a method called GetOrders, do you really need a stupid tooltip comment or a topic in a CHM file to tell you that this method "gets orders" ? Maybe you thought it would list the "orders of the gets", right? Then you bring up Intellisense suggestions and there's a property named UserName in your object, I'm sure you'd be totally puzzled wondering what it stands for, correct?

Hmmm, UserName, what could it possibly be. Ha! Thank you Mr. Tooltip you just saved my bacon. It's the name of the user. Phew, thank God I didn't need to use Reflector to figure this one out.

Sarcasm aside, what real benefit does such a tool gives you? You're just avoiding compiler warnings at most. If you want real useful content in your XML comments, they need to hand-written by someone who's thinking about the developer that will read them. A tool will not add examples, notes, tips, suggest other references, etc. Basically, if a freaking tool was able to guess what that member does, you must be able to guess it too before the tooltip comes up. The tool was not written to help the other developer. The tool was written to beat another tool (the compiler and its annoying warnings.) Use wisdom when choosing your tools. Not all of them are made equal.

What drove me over the edge to get this post out was seeing a tooltip like "Gets the name of the nick".