commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Benson <gudnabr...@gmail.com>
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 <tcurdt@vafer.org> 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.

Matt

>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message