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 06:30:29 GMT
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.

Phil


>
> - Jörg
>
>
> ---------------------------------------------------------------------
> 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