On 7/25/11 1:36 AM, luc.maison...@free.fr wrote:
> 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.
Please do not do this in any of [math], [pool] or [dbcp] unless and
until there is a way to get checkstyle to differentiate the truly
missing stuff from the missing inherit annotations.
Phil
>
> 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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
