Re: JavaDocs vs. Tests (was: Interview)



Kenneth P. Turvey wrote:

On Sat, 03 Oct 2009 21:57:58 -0400, Eric Sosman wrote:



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.

Here's a method chosen at random from Sun's JavaDocs, the addAll() method
from the Collection interface:

addAll

public boolean addAll(Collection c)

Adds all of the elements in the specified collection to this collection
(optional operation). The behavior of this operation is undefined if the
specified collection is modified while the operation is in progress. (This
implies that the behavior of this call is undefined if the specified
collection is this collection, and this collection is nonempty.)


How many units tests would be necessary to test that method? Maybe 2? 3? How
would a developer get more useful information from these 2 or 3 unit tests
than from the description above?

Also, does your friend write JavaDoc comments for her unit tests?

You mention that the unit tests will stay current; I presume you mean that
any changes in the method under test will force the unit test to change if
required, whereas no compiler forces JavaDoc description to keep step with
the described method. Which is fair enough.

Finally, you mention that the unit tests take no extra effort to maintain if
you're going to write them anyway; isn't the same true for JavaDoc
comments?


--
www.EdmundKirwan.com - Home of encapsulation theory
.



Relevant Pages

  • Looking for unit tests for Custom Provider
    ... Does anyone know of where a reasonably complete set of unit tests for ... Membership can be found? ... google has not been my friend. ...
    (microsoft.public.dotnet.framework.aspnet.security)
  • 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. ... For libraries, it certainly makes sense, but for applications.. ...
    (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)
  • 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: 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)