Xml documentation comments are like hairspray!

Published Saturday, February 14, 2004 8:58 AM

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.

by thycotic
Filed under: , , ,

Comments

# Daniel O'Connell said on Saturday, February 14, 2004 11:18 AM

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.

# TrackBack said on Saturday, February 14, 2004 11:26 AM

1 .Net, 1 Perl, 2 Rant, 2 WILY, 1 WTF?, 1 XML
Line du jour:

# Jonathan Cogley said on Saturday, February 14, 2004 12: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.

# Daniel O'Connell said on Saturday, February 14, 2004 9:03 PM

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.

# TrackBack said on Wednesday, August 18, 2004 10:00 AM