Images in this post missing? We recently lost them in a site migration. We're working to restore these as you read this. Should you need an image in an emergency, please contact us at imagehelp@codebetter.com
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".


Posted 01-30-2009 12:06 PM by sergiopereira
Filed under: , ,

[Advertisement]

Comments

DotNetKicks.com wrote Generated by a tool, not for human consumption
on 01-30-2009 3:25 PM

You've been kicked (a good thing) - Trackback from DotNetKicks.com

Eber Irigoyen wrote re: Generated by a tool, not for human consumption
on 01-30-2009 4:30 PM

I think it's generated by a tool, not for developer consumption, but managers like documentation, they get documentation

sergiopereira wrote re: Generated by a tool, not for human consumption
on 01-30-2009 4:44 PM

@Eber, interesting point. I doubt that many managers care for CHM files but, even if they do, this is the equivalent of filling sausages or making bologna. You know it's not real meat, but you might trick someone into eating it.

One guy that worked with me tried to fool our manager with GhostDoc CHM files. It worked for 15 minutes, until she opened the CHM and realized she had been punk'd.

Mike wrote re: Generated by a tool, not for human consumption
on 01-30-2009 7:56 PM

If warnings are errors and missing doc is an warning then it is a drag to have to manually write docs for unimportant members. Obviously not every member requires docs but VS doesn't know that either

sergiopereira wrote re: Generated by a tool, not for human consumption
on 01-30-2009 9:48 PM

@Mike, that's true. I'd just disable the warnings for missing XML comments. It's hard to use the tool to generate all the comments an then come back and improve the comments for the "important members". I think once you allow a tool like this into your IDE, it has the potential to exterminate all the truly useful comments just because it's so easy and quicker.

Marcin Budny wrote re: Generated by a tool, not for human consumption
on 01-31-2009 4:55 AM

Sergio, I think that GhostDoc is great tool that allows you to comment your code quicker. Suppose you have method with two obvious parameters and one not very clear. You autogenerate comment and substitute description for the third attribute. You can also supplement the methods description. GhostDoc isn't supposed to write comments for you, just to aid this process.

sergiopereira wrote re: Generated by a tool, not for human consumption
on 01-31-2009 11:47 AM

@Marcin, I wish that was how people used this tool. I'm not sure that's how it's promoted among developers, though. On the other hand, you could first try to give a better name for your parameter or method. Only if you can't come up with a name that clarifies everything, then you would resort to the XML comments, which is like giving up and telling the other developer to RTFM. I think GhostDoc can be a useful tool, but it's evil by default.

E.Z. wrote re: Generated by a tool, not for human consumption
on 02-01-2009 6:48 PM

Poor coders document their code poorly, no matter what tool you give them. Don't blame GhostDoc for someone's lazy comments.

I use GhostDoc because it automates the process of pushing comments for interfaces through to their implementing classes. For that feature (bizarrely missing from VS) alone, it's worth installing.

Alvin Ashcraft wrote re: Generated by a tool, not for human consumption
on 02-01-2009 9:05 PM

I agree with E.Z. I use GhostDoc and it gives me a nice starting point with my XML comments. I also enhanced the comment generation rules a bit to meet my own needs.

BTW... Here's a tip of avoid "name of the nick" if you use the rules that ship with the tool.   :)

A NickName property will generate "the name of the nick"

A Nickname property will generate "the nickname"

sergiopereira wrote re: Generated by a tool, not for human consumption
on 02-01-2009 9:13 PM

@Alvin, I know what caused the "name of the nick"  :) What ticked me off was that, after reviewing the rest of the XML comments in that project, I realized that  none of them had human intervention. They had all come from GhostDoc, i.e. they were worthless. Like I said, anything GhostDoc adds, is entirely unnecessary. Can it be used better? Sure it can. Do developers go back and fix the comments for member or parameters that they were not capable of making clear just by naming? I believe some do, but I haven't seen any yet.

Aaron wrote re: Generated by a tool, not for human consumption
on 02-02-2009 9:58 AM

One thing that is really useful about it, IMO, is that you can place the XML comments in your interfaces and when you move over to the implementation files, you do not need to copy and paste the comments as GhostDoc will pull all of hte comments from the implemented interface or better yet, from any underlying class.

Like others have stated, if you write code well, you have the tendency to write comments well.

Dew Drop - February 2, 2009 | Alvin Ashcraft's Morning Dew wrote Dew Drop - February 2, 2009 | Alvin Ashcraft's Morning Dew
on 02-02-2009 10:09 AM

Pingback from  Dew Drop - February 2, 2009 | Alvin Ashcraft's Morning Dew

sergiopereira wrote re: Generated by a tool, not for human consumption
on 02-02-2009 10:47 AM

@Aaron, that feature sounds useful when you hear about it, but if those interfaces where also commented with autogenerated text, then you're just propagating the unnecessary comments. It will be useful if the interfaces are well-commented, though.

Brian Johnston wrote re: Generated by a tool, not for human consumption
on 02-02-2009 6:53 PM

Sergio - I get what your saying and yes, it's just as bad to have crap comments as to have:

<summary>

Summary for Class1

</summary

As the code I inherited all over the place.   I rather have 0 comments in our code base than deal with the constant crap comments I see from those who came before me.

Tools like this just enable lazy people to be lazier.   You should have to pass a series of tests before they give you a copy of this tool and then have your code reviewed randomly to make sure your using it right or have your license revoked.

Jeremy Gray wrote re: Generated by a tool, not for human consumption
on 02-04-2009 6:21 PM

GhostDoc won't write your documentation for you, nor was it meant to. It will, however, help you write your documentation faster. It also encourages you to name things in an explanatory fashion, as doing so helps it help you write your documentation yet faster still. As a happy side effect, doing so results in code that is usually easier to understand even when not looking at the documentation.

It is a poor craftsman that blames their tools, and all that jazz.

joshka wrote re: Generated by a tool, not for human consumption
on 02-06-2009 8:25 AM

I often find it useful as sergio mentioned above to generate comments with ghost doc and then examine the english version that it creates. If the english version doesn't make sense, then the parameter name probably doesn't either and should be changed to something more meaningful.

About The CodeBetter.Com Blog Network
CodeBetter.Com FAQ

Our Mission

Advertisers should contact Brendan

Subscribe
Google Reader or Homepage

del.icio.us CodeBetter.com Latest Items
Add to My Yahoo!
Subscribe with Bloglines
Subscribe in NewsGator Online
Subscribe with myFeedster
Add to My AOL
Furl CodeBetter.com Latest Items
Subscribe in Rojo

Member Projects
DimeCasts.Net - Derik Whittaker

Friends of Devlicio.us
Red-Gate Tools For SQL and .NET

NDepend

SlickEdit
 
SmartInspect .NET Logging
NGEDIT: ViEmu and Codekana
LiteAccounting.Com
DevExpress
Fixx
NHibernate Profiler
Unfuddle
Balsamiq Mockups
Scrumy
JetBrains - ReSharper
Umbraco
NServiceBus
RavenDb
Web Sequence Diagrams
Ducksboard<-- NEW Friend!

 



Site Copyright © 2007 CodeBetter.Com
Content Copyright Individual Bloggers

 

Community Server (Commercial Edition)