commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Benson <>
Subject Re: [math] Inherits doc and @Override
Date Mon, 25 Jul 2011 13:31:29 GMT
On Mon, Jul 25, 2011 at 5:07 AM, Torsten Curdt <> wrote:
>>> Good code needs little javadocs.
>> I disagree strongly.
>> The Javadoc should present the public API (and should ideally be
>> written before the code - i.e. the code implements the docs).
>> If the only documentation is the code, it is much harder for users to
>> determine how to use the API.

I have to agree.  Ever programmed against cglib?  When depending on
libraries with no javadoc, I invariably find myself going to the code,
which I really shouldn't have to do.  Of course, I must admit that
even for libraries that appear to be reasonably well-documented (e.g.
Spring), I still often end up going to the code.

>> For some code (interfaces, abstract methods) only Javadoc is available.
> Did you even bother to read the blog post?

I read it, Torsten.  What I get from its main theme though is that you
are encouraging the class-level "book" comment one sees in e.g.
oac.jxpath.JXPathContext or Mockito's main Mockito class.  I suppose
that's a matter of preference, but personally I prefer to digest an
API in smaller bits than that.


> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message