Xml documentation comments are like hairspray!

The Refactoring folks talk about CodeSmell and CodeDeodorant.  The concept is that a code smell is when there is a feeling that something *could* be wrong with a piece of code.  CodeDeodorant is when an attempt is made to cover up the smell by adding whitespace (for “clarity”) or detailed comments to explain the code.  These are usually signs that the code needs improving ...

The arrival of automatic documentation tools like Javadoc and NDoc often triggers an impulse to generate reams of HTML documentation for your API.  However, documentation comments suffer from the same drawbacks as comments in the code:

• They are not executed and therefore could contain errors or could be out of date. 
• They are also a burden and time drain to keep updating as your API evolves.

If you are following TestDrivenDevelopment (TDD) then you already have a complete set of unit tests that exercise all the features of your code.  What better examples could you provide for your API then a full set of passing unit tests?

In conclusion, TDD makes XML documentation comments like hairspray.  Nice to look at, a pain to modify and certainly not essential! :-)

Disclaimer: If your customer agrees that a documented API brings business value or your API will be published to developers without a source code release, then by all means generate documentation.

Thanks to Jason Alexander from the nGallery team in helping formulate this idea.