commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Benson <gudnabr...@gmail.com>
Subject Re: [math] Inherits doc and @Override
Date Mon, 25 Jul 2011 15:05:40 GMT
On Mon, Jul 25, 2011 at 9:59 AM, Phil Steitz <phil.steitz@gmail.com> wrote:
> On 7/25/11 1:36 AM, luc.maisonobe@free.fr wrote:
>> Hi Jörg,
>>
>> ----- Mail original -----
>> De: "Jörg Schaible" <joerg.schaible@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-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message