Home > .NET, Extreme Programming, Java, Test Driven Development > Xml documentation comments are like hairspray!

Xml documentation comments are like hairspray!

The Refactoring folks talk about CodeSmell and CodeDeodorant. The concept is that a codesmell 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 animpulse 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.

Ifyou 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,TDDmakes 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 APIbrings 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.

  1. http://
    February 14, 2004 at 4:18 pm

    So, you advocate using undocumented, possibly incompelte code to document undocumented code instead of using possibly incomplete english text to document code. Why, considering:

    1) Not all developers like to read code in an attempt to understand how its used.
    2) The amount of text to read to understand a method using tests is probably 3 to 5 times as much as the actual documentation(and perhaps harder). 5 to 10 sentences can describe effects accurately in a decently sized method, how much code does it take you to specify allowed value ranges, if null is allowed, expected method call order(if appropriate), expected event order(when its appropriate), possible exceptions, underlying effects, what is expected by overridders, etc. Do you have time to read code for all of that for each method you use every day?
    3) Organization is bound to get fried, either you end up with *alot* of duplicated code or you end up with code that can’t be easily navigated, is either really desirable for documentation?
    4) Nothing forces tests to be complete, just correct. If you are discplined enough to ensure your tests cover *everything* you are certainly discplined enough to keep up with a few lines of comments.
    5) Tests don’t provide any development time hints(intellisense, etc).

    I for one have *no* interest in reading someone elses test code for hours to understand a library, nor do I really feel like examining the method code itself unless there is a problem with what is expected.
    In essence, tests don’t replace documentation, documentation doesn’t replace tests, they are different things.

    Maybe I just don’t understand.
    Or maybe I’m odd in that I don’t think C# is a language help files or novels should be written in.

  2. Jonathan Cogley
    February 14, 2004 at 5:49 pm

    Daniel,

    Thank you for your thorough response. You raise some great points!

    1) Agreed but in my experience developers prefer examples (especially working ones!) to blurbs.
    2) Probably true. Although if your tests were well factored (which they should be) then they should be easy to interpret.
    3) I don’t follow you on this one. Tests should follow requirements.
    4) I agree about discipline … as you say you can’t practice TDD without discipline. I think the issue is more with time. To keep good XML docs takes time … on our current project we don’t have it.
    5) Good point.

    I think my emphasis was more on inhouse development with TDD where CollectiveCodeOwnership (http://www.extremeprogramming.org/rules/collective.html) is important. In that case, a developer is possibly just as likely to use a method as modify it and in that case they better understand the tests.

  3. http://
    February 15, 2004 at 2:03 am

    1) I hate samples, they seem to be wrong as often as right.
    2) Interpretation is easy, doesn’t mean I want to, ;).
    3) It doesn’t seem likely to me that tests are going to provide a nice little index where I can look something up with three keystrokes. The main point is figuring out which file the test you need is in(assuming you are using a seperated test assembly) could be atleast a few steps more than help files.
    4) I don’t have that much of an issue of keeping docs up, it certainly takes less time than writing tests does. The other half of the point is that although tests are compiled, there is still no restriction that ensures your tests cover all of your codes behaviour, making them no better than documentation in that respect.

    I can see where it is of value internally, however I do think that maintaining a summary and parameter description in xml docs should be a level of responsibility that all developers can handle. Forcing documentation out of your IDE defeats half of the purpose of the IDE.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: