On Mon, Jul 25, 2011 at 9:59 AM, Phil Steitz <phil.ste...@gmail.com> wrote:
> 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.
>
I would hope for the same across Commons, for the same reasons. If we
hate boilerplate so much, let's come up with alternatives, e.g. using
Javadoc's customization facilities to minimize noise. What is
important is that we have some measure of confidence that what needs
to be documented has been.
Matt
> 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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
