Re: JavaDocs vs. Tests



Kenneth P. Turvey wrote:
On Sat, 03 Oct 2009 21:57:58 -0400, Eric Sosman wrote:

When I'm writing a new method, I start with a nebulous
idea of what the thing is supposed to to (if I had no such notion, I
wouldn't have a reason to write the method at all). Step One is to write
a rough copy of what will eventually be the Javadoc; during the process
I discover the foggy patches in my nebulous idea, shine light into the
corner cases, and so on. Then I code the method (possibly coming up
with yet a few more tweaks along the way), and finally I turn the rough
draft into real Javadoc. (This is why even my private methods have doc
comments: They're my explanation to me of whatever folly I had in mind
at the time of coding.)

A friend of mine and I have been exchanging thoughts on just this topic over the last couple of nights. When I deliver source code my clients expect some level of documentation in the code, but my friend is certain that comments should really be left out and instead use the unit tests as documentation for what the method actually does.

This makes sense in a couple of different ways. A developer will get more useful information from a unit test than he will from the docs. In addition the unit tests will stay current and don't take any extra effort to maintain if you are going to write them anyway.

I don't have a firm opinion on this. I know my clients are going to want JavaDocs. I'm not sure where I stand on whether this is reasonable or not. For libraries, it certainly makes sense, but for applications.. I'm not sure it does.

I have a firm opinion on it - if you give me a Java library and it's not commented with Javadoc, I'm not going to use it. I don't care if someone has already helpfully run the javadoc tool on it and included a ZIP of the HTML; I can do that myself. But the comments themselves had best be there.

Personally I don't even want to look at someone's unit tests for their library. I'm a consumer of that library's public API, not a developer of its code.

AHS
.