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-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
