Hi Jörg,
----- Mail original -----
De: "Jörg Schaible" <joerg.schai...@scalaris.com>
À: dev@commons.apache.org
Envoyé: Lundi 25 Juillet 2011 09:19:36
Objet: Re: [math] Inherits doc and @Override
>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.
I agree with the rationale, but not with the conclusion. I don't think we have
that much committers that would simply hit the IDE keystroke to build bad
javadoc all the time. So when the javadoc should be extended, it is written,
and when it can be reduced, it is. So a simple {@inheritDoc} does provide me
an information, mainly that this code is a simple inheritance and its spec is
fully defined by the upper class. A completely missing javadoc makes me wonder
it it is something that was forgotten, or a simple inheritance like in the
former
case.
> 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
I agree, it is philosophical, and I won't either go further in this discussion,
so if other decide those simple {@inheridDoc} are bad, then they can remove
them.
> 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. :)
I'm sure I will get used to this view if we try it. It will just take a few
time to
get accustomed to it. So once again, if someone feels the need to give it a try
and
write the small script that will wipe these on-liners in one command, don't
hesitate.
best regards,
Luc
>
> - Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
