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
.



Relevant Pages

  • JavaDocs vs. Tests (was: Interview)
    ... wouldn't have a reason to write the method at all). ... draft into real Javadoc. ... that comments should really be left out and instead use the unit tests as ... documentation for what the method actually does. ...
    (comp.lang.java.programmer)
  • Re: JavaDocs vs. Tests
    ... wouldn't have a reason to write the method at all). ... draft into real Javadoc. ... 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. ... in many cases the reader will interpolate and extrapolate in ...
    (comp.lang.java.programmer)
  • Re: JavaDocs vs. Tests (was: Interview)
    ... A friend of mine and I have been exchanging thoughts on just this topic ... that comments should really be left out and instead use the unit tests as ... Adds all of the elements in the specified collection to this collection ... does your friend write JavaDoc comments for her unit tests? ...
    (comp.lang.java.programmer)
  • Re: TDD: Test-Driven Design or Test-Driven Development?
    ... >> kinds of design documentation. ... >although you had access to the source and unit tests? ... I'm thinking of the standard API. ... I'd first like to see the javadoc. ...
    (comp.object)
  • Re: Static typing
    ... Like unit tests, they verify that for some input values, the ... Unless the static type system takes away the expressive power that I need. ... There's no reason ... Please take a look at the Smalltalk MOP or the CLOS MOP and tell ...
    (comp.lang.python)