commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jörg Schaible <joerg.schai...@scalaris.com>
Subject Re: [math] Inherits doc and @Override
Date Mon, 25 Jul 2011 07:19:36 GMT
Hi Phil,

Phil Steitz wrote:

> On 7/24/11 10:52 PM, Jörg Schaible wrote:
>> Hi Phil,
>>
>> Phil Steitz wrote:
>>
>>> On 7/24/11 3:13 PM, Gilles Sadowski wrote:
>>>> Hello.
>>>>
>>>>> I saw in the sources serveral /** {@inheritDoc} */ on methods with
>>>>> @Override annotation. Javadoc knows to inherit the javadoc of the
>>>>> overwritten methos, so there is no need for @inheritDoc.
>>>>> If all agree, one could drop this if the code is modified?
>>>> CheckStyle complains if there isn't a Javadoc block.
>> Bad argument. Adjust the rule.
>>
>>> Right, and including it creates a placeholder to expand on or modify
>>> the inherited javadoc.  I think we should keep it.
>> We finally removed it in our code base here at my company and it looks so
>> much cleaner. Why keep superfluous lines of "boiler plate stuff" without
>> any relevance? If there is something to document on, I'd expect a little
>> more than {@inheritDoc} anyway.
> 
> Here's the problem as I see it.  Code with no javadoc is bad, bad,
> bad.   Especially for library code, which is what we do here.
> Removing the check opens the door to this badness.  Maybe a "bad
> argument" but practical (unless there is some simple checkstyle
> magic that I don't know about, which is quite possible).  Secondly,
> every time I paste in {@inheritDoc} or see it in our code, I ask
> myself if the inherited doc is accurate and adequate.  I know you
> may respond that the same could apply just looking at the @Override
> and emptiness, but I personally like seeing the javadoc block
> there.  I won't complain about removal if we can find a way to keep
> the check functioning without adding ad hoc work for committers; but
> I don't personally see this as a problem.

what I've actually observed is, that developers who do not document, will 
also happily ignore any boiler plate @inheritDoc. Having checkstyle to look 
for it does not help, because such a developer has configured his IDE to add 
the boiler plate anyway. Therefore I'd rather see clean code (especially for 
wrappers) than having a lot of pointless lines that *I* simply call clutter 
here.

We all know, that this discussion is in the end philosophical only and 
neither I want to enforce any general rule nor am I religious about this 
issue, but do me a favor and try it yourself. Take some code with a lot of 
this boiler plate stuff, remove it and let the cleaned code sink in for a 
while. :)

- Jörg


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


Mime
View raw message