From: Steve B. <Ste...@an...> - 2012-05-02 23:30:35
|
Sorry for not noticing this change earlier. I don't understand the rationale for the removal of comments that are duplicated on overridden methods (ie method in subclass carries the same comment as method in superclass). Sorry if I'm being stupid here, but this duplication seems helpful/necessary (at least with the Eclipse IDE) because the comments are ostensibly useful, and when I'm walking through a class it seems unhelpful to have them elided (even though I can push up through the hierarchy (sometimes deep) to find them. To be clear, I'm all for standardization and application good practice, but it's just not immediately obvious to me that removing these comments is a good thing. (I'm also very appreciative of Eric's substantial effort in pushing these changes through). Can someone enlighten me? Thanks, --Steve On 03/05/2012, at 2:10 AM, jik...@li... wrote: > > details: http://jikesrvm.hg.sourceforge.net/hgweb/jikesrvm/jikesrvm/rev/0d21d93c0db1 > changeset: 10446:0d21d93c0db1 > user: Erik Brangs <eri...@gm...> > date: Fri Apr 27 22:26:43 2012 +0200 > description: > RVM-962: Remove duplicated comments from org.mmtk.plan and org.mmtk.plan.* packages. |
From: David P G. <gr...@us...> - 2012-05-03 00:57:42
|
Steve Blackburn <Ste...@an...> wrote on 05/02/2012 07:29:53 PM: > From: Steve Blackburn <Ste...@an...> > To: jik...@li..., > Date: 05/02/2012 07:31 PM > Subject: Re: [rvm-core] [rvm-commits] jikesrvm: 13 new changesets > > Sorry for not noticing this change earlier. > > I don't understand the rationale for the removal of comments that > are duplicated on overridden methods (ie method in subclass carries > the same comment as method in superclass). Sorry if I'm being > stupid here, but this duplication seems helpful/necessary (at least > with the Eclipse IDE) because the comments are ostensibly useful, > and when I'm walking through a class it seems unhelpful to have them > elided (even though I can push up through the hierarchy (sometimes > deep) to find them. > > To be clear, I'm all for standardization and application good > practice, but it's just not immediately obvious to me that removing > these comments is a good thing. (I'm also very appreciative of > Eric's substantial effort in pushing these changes through). > > Can someone enlighten me? > Hi Steve, The motivation was discussed mid-April on this thread: http://sourceforge.net/mailarchive/message.php?msg_id=29121555 Summarizing, as long as the methods are tagged with @Override then there's an argument that avoiding the duplicated comments is better, since it avoids inconsistent maintenance operations that result in unintended differences between comments on sub/superclass methods. --dave |
From: Steve B. <Ste...@an...> - 2012-05-03 01:15:12
|
Thanks Dave. My oversight. I think Eric's argument is reasonable. I understand the argument in principle, but how it plays out in an intensive, deep debugging session may be different. So the rule now is that comments must not be _duplicated_ when methods are overridden. The writer has two choices: a) empty comment (comment deferred up hierarchy) or b) comment specific to the overriding behavior. By corollary, we should be stricter in our use of the @Override annotation (which I gather Eric is picking up on anyway). I'm happy with the change (at least for now :-). --Steve On 03/05/2012, at 10:55 AM, David P Grove wrote: > Steve Blackburn <Ste...@an...> wrote on 05/02/2012 07:29:53 PM: > > > From: Steve Blackburn <Ste...@an...> > > To: jik...@li..., > > Date: 05/02/2012 07:31 PM > > Subject: Re: [rvm-core] [rvm-commits] jikesrvm: 13 new changesets > > > > Sorry for not noticing this change earlier. > > > > I don't understand the rationale for the removal of comments that > > are duplicated on overridden methods (ie method in subclass carries > > the same comment as method in superclass). Sorry if I'm being > > stupid here, but this duplication seems helpful/necessary (at least > > with the Eclipse IDE) because the comments are ostensibly useful, > > and when I'm walking through a class it seems unhelpful to have them > > elided (even though I can push up through the hierarchy (sometimes > > deep) to find them. > > > > To be clear, I'm all for standardization and application good > > practice, but it's just not immediately obvious to me that removing > > these comments is a good thing. (I'm also very appreciative of > > Eric's substantial effort in pushing these changes through). > > > > Can someone enlighten me? > > > > Hi Steve, > > The motivation was discussed mid-April on this thread: http://sourceforge.net/mailarchive/message.php?msg_id=29121555 > > Summarizing, as long as the methods are tagged with @Override then there's an argument that avoiding the duplicated comments is better, since it avoids inconsistent maintenance operations that result in unintended differences between comments on sub/superclass methods. > > --dave > ------------------------------------------------------------------------------ > Live Security Virtual Conference > Exclusive live event will cover all the ways today's security and > threat landscape has changed and how IT managers can respond. Discussions > will include endpoint security, mobile security and the latest in malware > threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/_______________________________________________ > Jikesrvm-core mailing list > Jik...@li... > https://lists.sourceforge.net/lists/listinfo/jikesrvm-core |
From: Erik B. <eri...@gm...> - 2012-05-03 09:52:12
|
Hi, > By corollary, we should be stricter in our use of the > @Override annotation (which I gather Eric is picking up on anyway). If you're using Eclipse, you can configure the Save Actions to automatically add missing @Override annotations. That's probably the easiest way if don't mind Eclipse changing the source code without asking you. If you do mind, you can use the Cleanup feature with a custom profile. On a somewhat related sidenote, the advice for setting up IDEs for Jikes RVM on the wiki page could be improved. In particular, it's quite Eclipse-centric. Contributions from people using other IDEs would be very welcome. Kind regards, Erik Brangs |
From: Andreas S. <se...@st...> - 2012-05-03 07:28:04
|
Hi, > So the rule now is that comments must not be _duplicated_ when methods > are overridden. The writer has two choices: a) empty comment (comment > deferred up hierarchy) or b) comment specific to the overriding > behavior. There's also choice c) (a variation of b): Use {@inheritDoc} <http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc> to augment the description of the overriding behaviour. I think this is preferable to option b) in most cases (because of the Liskov substitution principle and all that); you don't throw away information about the overridden behaviour but can avoid copy & paste. And yes, Eclipse expands {@inheritDoc}s automatically on hovering over the source code element in question, so no problem there. Best wishes, Andreas |
From: Erik B. <eri...@gm...> - 2012-05-03 09:57:58
|
Hi, > There's also choice c) (a variation of b): Use {@inheritDoc} > <http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc> > to augment the description of the overriding behaviour. I think this is > preferable to option b) in most cases (because of the Liskov > substitution principle and all that); you don't throw away information > about the overridden behaviour but can avoid copy& paste. there are comments where {@inheritDoc} could be used in such a way, particularly in MMTk. I could change these comments to use {@inheritDoc} with my next patch for the JavaDoc (the one with the cosmetic comment changes) if nobody has any objections. Kind regards, Erik Brangs |
From: Steve B. <Ste...@an...> - 2012-05-03 10:00:03
|
On 03/05/2012, at 7:57 PM, Erik Brangs wrote: > there are comments where {@inheritDoc} could be used in such a way, > particularly in MMTk. I could change these comments to use {@inheritDoc} > with my next patch for the JavaDoc (the one with the cosmetic comment > changes) if nobody has any objections. This sounds sensible. --Steve |
From: David P G. <gr...@us...> - 2012-05-03 01:17:13
|
Sorry, I hit return too soon... The other point is that if you are in Eclipse, when you "hover" over a method declaration with an @Override that has no javadoc itself, Eclipse will show you the javadoc from higher up the hierarchy automatically. --dave |