This week's book giveaway is in the Performance forum.
We're giving away four copies of The Java Performance Companion and have Charlie Hunt, Monica Beckwith, Poonam Parhar, & Bengt Rutisson on-line!
See this thread for details.
Win a copy of The Java Performance Companion this week in the Performance forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Leaving the provided interface comments unchanged?

 
Yucca Nel
Ranch Hand
Posts: 147
IntelliJ IDE Java Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
What are the rules as far as the interface provided are concerned? Must the interface be left untouched and unchanged? There are some annoying line comments that I would prefer to change into javadoc comments. Can I do this? Must the comments be left there? etc etc.
 
K. Tsang
Bartender
Posts: 3457
14
Android Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Yucca,

I personally don't see why the interface's comments need to be changed. If you understand those comments, you would know what to do (how to implement). If you don't understand, then you should post your worries.

Also Sun's given interface is just the "must implement" methods. Many other people feel that there are other "must" implement methods that should be included in the interface file. It is up to you where these other methods go.

Hope this helps.
 
Roberto Perillo
Bartender
Posts: 2271
3
Eclipse IDE Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
No, the interface cannot be changed. About the comments, I guess you can change them, since they won't interfere in the program's execution. I prefered to leave them just as I received them, but used JavaDoc comments, instead of code comments.
 
Yucca Nel
Ranch Hand
Posts: 147
IntelliJ IDE Java Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
So would you say that its ok to change this...

to this...


or this ...


Option 2 looks better and still provides the commenting in my opinion
 
K. Tsang
Bartender
Posts: 3457
14
Android Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
option 1 will do the trick. Since you need to generate javadocs. That is absolutely fine as javadoc for the read method.
 
Yucca Nel
Ranch Hand
Posts: 147
IntelliJ IDE Java Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you for replies.
 
Alecsandru Cocarla
Ranch Hand
Posts: 158
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I also added my own comments to those from SUN, especially at the lock() method where I added some more rules to follow in order to avoid deadlocks. I also javadoc'ed runtime exceptions that I chose to throw.

I don't see why the comments cannot be changed, since they are not part of the actual interface, they're not affecting how the interface looks like in terms of code.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic