You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Arne Ploese <ap...@gmx.de> on 2011/07/22 08:18:06 UTC
[math] Inherits doc and @Override
Hi,
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?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by Konstantin Kolinko <kn...@gmail.com>.
2011/7/22 Arne Ploese <ap...@gmx.de>:
> Hi,
>
> 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?
For reference, previous discussion, April 2011 "[lang] @inheritDoc":
http://markmail.org/thread/jvn4nm6uilmjytw4
Best regards,
Konstantin Kolinko
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by Ted Dunning <te...@gmail.com>.
Also, the compiler is probably more accurate at keeping inherited
documentation up to date.
On Sun, Jul 24, 2011 at 10:52 PM, Jörg Schaible <joerg.schaible@scalaris.com
> wrote:
>
> > 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.
>
Re: [math] Inherits doc and @Override
Posted by Phil Steitz <ph...@gmail.com>.
On 7/25/11 6:31 AM, Matt Benson wrote:
> On Mon, Jul 25, 2011 at 5:07 AM, Torsten Curdt <tc...@vafer.org> wrote:
>>>> Good code needs little javadocs.
>>> I disagree strongly.
>>>
>>> The Javadoc should present the public API (and should ideally be
>>> written before the code - i.e. the code implements the docs).
>>>
>>> If the only documentation is the code, it is much harder for users to
>>> determine how to use the API.
> I have to agree. Ever programmed against cglib? When depending on
> libraries with no javadoc, I invariably find myself going to the code,
> which I really shouldn't have to do. Of course, I must admit that
> even for libraries that appear to be reasonably well-documented (e.g.
> Spring), I still often end up going to the code.
>
>>> For some code (interfaces, abstract methods) only Javadoc is available.
>> Did you even bother to read the blog post?
> I read it, Torsten. What I get from its main theme though is that you
> are encouraging the class-level "book" comment one sees in e.g.
> oac.jxpath.JXPathContext or Mockito's main Mockito class. I suppose
> that's a matter of preference, but personally I prefer to digest an
> API in smaller bits than that.
Honestly, I think its best to have both. Good class-level javadoc
describes the overall function of the class, primary properties and
use cases and macro-level considerations about what the class
expects from or how it interacts with its execution environment.
Method level javadoc specifies contracts. If you have to skimp on
one of these, for library code it is in general better to focus on
the method-level documentation, because that is what the user always
sees and depends on and also what can be validated by the unit tests.
Phil
>
> Matt
>
>> ---------------------------------------------------------------------
>> 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
Re: [math] Inherits doc and @Override
Posted by Matt Benson <gu...@gmail.com>.
On Mon, Jul 25, 2011 at 10:27 AM, Torsten Curdt <tc...@vafer.org> wrote:
>>> Maybe I am working too much in other languages to appreciate the "less
>>> is more" way of coding.
>>> Self descriptive code is less a myth but more a state of mind when
>>> writing that code and documentation.
>>
>> The problem with that "state of mind" is that unless and until you
>> clearly specify a contract for your code (and write tests to
>> validate it) you - and your users - don't really know what it does.
>
> With the "state of mind" I mean: think like the user and what matters to him.
> So I am mostly with you - you just haven't have realized that ;)
>
> No one is saying that describing an API is useless. In fact I am
> saying the exact opposite. I just question the idea of describing
> every method being useful. When you say that the following javadocs
> are useful - then there is probably not much left to discuss anyway:
I understood where you are coming from, Torsten, hence my
pseudo-suggestion (pseudo- in that I don't personally have time to do
it) that we use some custom mechanisms for the best of both worlds.
As I see it, using checkstyle, etc., to require that Javadoc is in
place (and I really agree that documentation requirements should focus
on non-private members) is our best available means of verifying that
we have attempted to provide adequate documentation. For me, using
@inheritDoc (without elaboration) is a way to say "I have evaluated
this method, and I believe that it does nothing remarkable beyond what
might be expected of the given subclass in the context of the defined
operation." A custom doclet might for example accomplish the same
thing using a custom annotation, eliminating the wrapping javadoc
comment. Opinions will vary as to whether this very slight savings in
code size would justify the work of implementing it, but this is only
an example of certain conventions upon which we might agree so that
our javadoc is as complete as it needs to be, while our code is
allowed to be as clean as it can be. Our API documentation isn't
perfect just because javadocs are required, but it's probably better
than it would be if they weren't.
Matt
>
> /** Serial */
> private static final long serialVersionUID = 1234L;
>
> /** The Foo's user id. */
> private int userId;
>
> /**
> * Constructor
> */
> public Foo () {
>
> /**
> * Get this Foo's name.
> *
> * @return This Foo's name.
> */
> public String getName() {
>
> /**
> * Set this Foo's name.
> *
> * @param name This Foo's new name.
> */
> public void setName(String name) {
>
> cheers,
> Torsten
>
> ---------------------------------------------------------------------
> 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
Re: [math] Inherits doc and @Override
Posted by Phil Steitz <ph...@gmail.com>.
On 7/25/11 8:27 AM, Torsten Curdt wrote:
>>> Maybe I am working too much in other languages to appreciate the "less
>>> is more" way of coding.
>>> Self descriptive code is less a myth but more a state of mind when
>>> writing that code and documentation.
>> The problem with that "state of mind" is that unless and until you
>> clearly specify a contract for your code (and write tests to
>> validate it) you - and your users - don't really know what it does.
> With the "state of mind" I mean: think like the user and what matters to him.
> So I am mostly with you - you just haven't have realized that ;)
I get your point. The problem that I have never been able to solve,
though, is where to draw the line. My HO is that as soon as you
open the door to people saying "obvious" and omitting method
javadoc, things devolve rather quickly. This is especially true
when it comes to "self-documenting" method names. The examples
below certainly look innocuous at first. But what happens when one
of the setters is changed to have a side effect? Or when new
constraints are placed on the property? And where, other than the
getter, do you document what the property means? I guess when
things become nontrivial, you decide it is no longer "obvious" and
add javadoc. Again, having been burned by seemingly "obvious" code
many times (including a long and painful experience deciphering
earlier versions of [pool] and [dbcp] that had terrible javadoc), my
admittedly conservative tendency is to want to create the right
documentation structure at the beginning rather than having to keep
track of when things become no longer "obvious."
Phil
>
> No one is saying that describing an API is useless. In fact I am
> saying the exact opposite. I just question the idea of describing
> every method being useful. When you say that the following javadocs
> are useful - then there is probably not much left to discuss anyway:
>
> /** Serial */
> private static final long serialVersionUID = 1234L;
>
> /** The Foo's user id. */
> private int userId;
>
> /**
> * Constructor
> */
> public Foo () {
>
> /**
> * Get this Foo's name.
> *
> * @return This Foo's name.
> */
> public String getName() {
>
> /**
> * Set this Foo's name.
> *
> * @param name This Foo's new name.
> */
> public void setName(String name) {
>
> cheers,
> Torsten
>
> ---------------------------------------------------------------------
> 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
Re: [math] Inherits doc and @Override
Posted by Torsten Curdt <tc...@vafer.org>.
>> Maybe I am working too much in other languages to appreciate the "less
>> is more" way of coding.
>> Self descriptive code is less a myth but more a state of mind when
>> writing that code and documentation.
>
> The problem with that "state of mind" is that unless and until you
> clearly specify a contract for your code (and write tests to
> validate it) you - and your users - don't really know what it does.
With the "state of mind" I mean: think like the user and what matters to him.
So I am mostly with you - you just haven't have realized that ;)
No one is saying that describing an API is useless. In fact I am
saying the exact opposite. I just question the idea of describing
every method being useful. When you say that the following javadocs
are useful - then there is probably not much left to discuss anyway:
/** Serial */
private static final long serialVersionUID = 1234L;
/** The Foo's user id. */
private int userId;
/**
* Constructor
*/
public Foo () {
/**
* Get this Foo's name.
*
* @return This Foo's name.
*/
public String getName() {
/**
* Set this Foo's name.
*
* @param name This Foo's new name.
*/
public void setName(String name) {
cheers,
Torsten
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by Phil Steitz <ph...@gmail.com>.
On 7/25/11 6:55 AM, Torsten Curdt wrote:
> I am not saying don't use javadocs. It's all about using javadocs effectively.
>
> Forcing javadocs on all methods leads to bloat and noise. Better
> present stellar javadocs on public APIs and document how the library
> works. Having great examples helps a great deal ...but don't (please
> don't!) use Eclipse to auto-complete javadocs or have useless javadocs
> on setters/getters. Instead think when you write.
>
> How much is obvious from the method signature already? What is not?
> Not sure there is a checkstyle rule for that.
>
> Maybe I am working too much in other languages to appreciate the "less
> is more" way of coding.
> Self descriptive code is less a myth but more a state of mind when
> writing that code and documentation.
The problem with that "state of mind" is that unless and until you
clearly specify a contract for your code (and write tests to
validate it) you - and your users - don't really know what it does.
That may be fun and fine for small bits of code or even whole
applications developed by a small, close-nit team. It fails
miserably when others start depending on it or when the
implementation or execution environment of the code changes. Having
to try to reverse engineer the thought process of a developer whose
excellent idea is described only "in beautiful, self-describing
code" is no fun, especially when that code has failed or delivered
unexpected results. Please lets no go there in Commons.
Phil
>
> Anyway ...I'll shut up now :)
>
> ---------------------------------------------------------------------
> 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
Re: [math] Inherits doc and @Override
Posted by Torsten Curdt <tc...@vafer.org>.
I am not saying don't use javadocs. It's all about using javadocs effectively.
Forcing javadocs on all methods leads to bloat and noise. Better
present stellar javadocs on public APIs and document how the library
works. Having great examples helps a great deal ...but don't (please
don't!) use Eclipse to auto-complete javadocs or have useless javadocs
on setters/getters. Instead think when you write.
How much is obvious from the method signature already? What is not?
Not sure there is a checkstyle rule for that.
Maybe I am working too much in other languages to appreciate the "less
is more" way of coding.
Self descriptive code is less a myth but more a state of mind when
writing that code and documentation.
Anyway ...I'll shut up now :)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by Matt Benson <gu...@gmail.com>.
On Mon, Jul 25, 2011 at 5:07 AM, Torsten Curdt <tc...@vafer.org> wrote:
>>> Good code needs little javadocs.
>>
>> I disagree strongly.
>>
>> The Javadoc should present the public API (and should ideally be
>> written before the code - i.e. the code implements the docs).
>>
>> If the only documentation is the code, it is much harder for users to
>> determine how to use the API.
I have to agree. Ever programmed against cglib? When depending on
libraries with no javadoc, I invariably find myself going to the code,
which I really shouldn't have to do. Of course, I must admit that
even for libraries that appear to be reasonably well-documented (e.g.
Spring), I still often end up going to the code.
>>
>> For some code (interfaces, abstract methods) only Javadoc is available.
>
> Did you even bother to read the blog post?
I read it, Torsten. What I get from its main theme though is that you
are encouraging the class-level "book" comment one sees in e.g.
oac.jxpath.JXPathContext or Mockito's main Mockito class. I suppose
that's a matter of preference, but personally I prefer to digest an
API in smaller bits than that.
Matt
>
> ---------------------------------------------------------------------
> 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
Re: [math] Inherits doc and @Override
Posted by Torsten Curdt <tc...@vafer.org>.
>> Good code needs little javadocs.
>
> I disagree strongly.
>
> The Javadoc should present the public API (and should ideally be
> written before the code - i.e. the code implements the docs).
>
> If the only documentation is the code, it is much harder for users to
> determine how to use the API.
>
> For some code (interfaces, abstract methods) only Javadoc is available.
Did you even bother to read the blog post?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by sebb <se...@gmail.com>.
On 25 July 2011 09:13, Torsten Curdt <tc...@vafer.org> wrote:
>> Here's the problem as I see it. Code with no javadoc is bad, bad,
>> bad.
+1
> Good code needs little javadocs.
I disagree strongly.
The Javadoc should present the public API (and should ideally be
written before the code - i.e. the code implements the docs).
If the only documentation is the code, it is much harder for users to
determine how to use the API.
For some code (interfaces, abstract methods) only Javadoc is available.
>
> http://vafer.org/blog/20050323095453/
>
> Good docs and good code over noise - any time.
> cheers,
> Torsten
>
> ---------------------------------------------------------------------
> 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
Re: [math] Inherits doc and @Override
Posted by Phil Steitz <ph...@gmail.com>.
On 7/25/11 1:13 AM, Torsten Curdt wrote:
>> Here's the problem as I see it. Code with no javadoc is bad, bad,
>> bad.
> Good code needs little javadocs.
>
> http://vafer.org/blog/20050323095453/
>
> Good docs and good code over noise - any time.
Umm....no.
Without method javadoc, library code is *worthless*
The javadoc we maintain in our components represents our contract
with users. Same is true for any code that is ever going to be used
by anyone other than the original author or a small group hacking
directly on the sources. When code reuse devolves into cut and
paste only or random hacking on a shared hairball, the author above
is correct - everyone can just look at the code. Reusable
components and durable code need real javadoc. Vague hand-wavy
stuff at the class level or "revealing names" do not cut it. The
key point is that a good component is reusable *without looking at
the sources*. Imagine if the JDK were developed without javadoc.
Would you really want to have to go look at the source every time
you used a JDK class?
Phil
>
> cheers,
> Torsten
>
> ---------------------------------------------------------------------
> 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
Re: [math] Inherits doc and @Override
Posted by Torsten Curdt <tc...@vafer.org>.
> Here's the problem as I see it. Code with no javadoc is bad, bad,
> bad.
Good code needs little javadocs.
http://vafer.org/blog/20050323095453/
Good docs and good code over noise - any time.
cheers,
Torsten
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by Matt Benson <gu...@gmail.com>.
On Mon, Jul 25, 2011 at 9:59 AM, Phil Steitz <ph...@gmail.com> wrote:
> On 7/25/11 1:36 AM, luc.maisonobe@free.fr wrote:
>> Hi Jörg,
>>
>> ----- Mail original -----
>> De: "Jörg Schaible" <jo...@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
Re: [math] Inherits doc and @Override
Posted by Phil Steitz <ph...@gmail.com>.
On 7/25/11 1:36 AM, luc.maisonobe@free.fr wrote:
> Hi Jörg,
>
> ----- Mail original -----
> De: "Jörg Schaible" <jo...@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-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
Re: [math] Inherits doc and @Override
Posted by lu...@free.fr.
Hi Jörg,
----- Mail original -----
De: "Jörg Schaible" <jo...@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-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
Re: [math] Inherits doc and @Override
Posted by Jörg Schaible <jo...@scalaris.com>.
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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by Phil Steitz <ph...@gmail.com>.
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.
Phil
>
> - 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
Re: [math] Inherits doc and @Override
Posted by Jörg Schaible <jo...@scalaris.com>.
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.
- Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Inherits doc and @Override
Posted by Phil Steitz <ph...@gmail.com>.
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.
Right, and including it creates a placeholder to expand on or modify
the inherited javadoc. I think we should keep it.
Phil
>
>
> Regards,
> Gilles
>
> ---------------------------------------------------------------------
> 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
Re: [math] Inherits doc and @Override
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
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.
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org