commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
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.


> - Jörg
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

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

View raw message