• Post Reply Bookmark Topic Watch Topic
  • New Topic

Javadoc comments on actionperformed methods  RSS feed

 
Terry Flint
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I'm a little confused about something. As far as I understand, there is a rule that all public methods must have javadoc comments, and as far as I can tell an actionperformed method within an action listener is public. Nevertheless, I can't help feeling a bit unsure about whether to comment them or not. Something about it seems incredibly counterintuitive. The fact that I can't find any examples o it also puts me off, so I'd like to know one way or the other.Are you supposed to write javadoc comments for actionperformed methods?
 
Ivan Jozsef Balazs
Rancher
Posts: 999
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
As far as I understand, there is a rule that all public methods must have javadoc comment


Where is it stated? What kind of rule?

At most a recommendation...

The method "actionPerformed" is a well known part of the API, I would not document its implementation just for documentation's sake either.


Notes on Programming in C by Rob Pike

Rob Pike wrote:
Comments
A delicate matter, requiring taste and judgement. I tend to err on the side of eliminating comments, for several reasons.
 
Maneesh Godbole
Bartender
Posts: 11445
18
Android Eclipse IDE Google Web Toolkit Java Mac Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
IMO you should provide proper comments where possible. If your code does nothing special but provide a concrete implementation for some method (e.g. actionPerformed) you can use the

Check out the "referenced classes" section in http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html
 
Winston Gutkowski
Bartender
Posts: 10575
66
Eclipse IDE Hibernate Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Terry Flint wrote:The fact that I can't find any examples o it also puts me off, so I'd like to know one way or the other.

That's because ActionListener is an interface, and is often implemented as an anonymous class. That doesn't mean you can't document it; just that you'll probably never see it in the API.

Are you supposed to write javadoc comments for actionperformed methods?

I do; and I'm afraid I have to disagree the esteemed Mr. Pike here - I tend to err on the side of over-documenting.

There is one thing he says in the same section as the quote provided which is very important though:
Rob Pike wrote:...comments aren't checked by the compiler, so there is no guarantee they're right, especially after the code is modified.
so the trick is that your comments should focus on WHAT the method does, not on HOW it does it (for more info, see the WhatNotHow page).

I would agree with Ivan that it's worth checking the documentation of the overridden method though: If you've got a button called CloseButton, and your actionPerformed() method simply closes your app, a comment stating that that's what it does seems a bit redundant.

Winston
 
Terry Flint
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks everyone. All the extra reading was very informative, and now I think I have a better understanding of exactly when to comment my code. Basically, if it adds to the explanation then go for it. If it's redundant, don't bother.
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!