commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [math] Inherits doc and @Override
Date Mon, 25 Jul 2011 14:56:56 GMT
On 7/25/11 1:13 AM, Torsten Curdt wrote:
>> Here's the problem as I see it.  Code with no javadoc is bad, bad,
>> bad.
> Good code needs little javadocs.
>
>  http://vafer.org/blog/20050323095453/
>
> Good docs and good code over noise - any time.

Umm....no. 

Without method javadoc, library code is *worthless*

The javadoc we maintain in our components represents our contract
with users.  Same is true for any code that is ever going to be used
by anyone other than the original author or a small group hacking
directly on the sources.   When code reuse devolves into cut and
paste only or random hacking on a shared hairball, the author above
is correct - everyone can just look at the code.  Reusable
components and durable code need real javadoc.  Vague hand-wavy
stuff at the class level or "revealing names" do not cut it.  The
key point is that a good component is reusable *without looking at
the sources*.  Imagine if the JDK were developed without javadoc. 
Would you really want to have to go look at the source every time
you used a JDK class?

Phil
>
> cheers,
> Torsten
>
> ---------------------------------------------------------------------
> 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