This week's book giveaway is in the Jobs Discussion forum.
We're giving away four copies of Customer Requirements for Developers and have Marcho Behler on-line!
See this thread for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes B&S: Javadoc in Sun's data interface allowed? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login

Win a copy of Customer Requirements for Developers this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "B&S: Javadoc in Sun Watch "B&S: Javadoc in Sun New topic

B&S: Javadoc in Sun's data interface allowed?

Darya Akbari
Ranch Hand

Joined: Aug 21, 2004
Posts: 1855
Hi all,

I am really afraid to even touch Sun's provided data interface ( So far I only did some indenting to be conform with the code convention.

But now I come to the point where I do the javadoc class and interface documentation.

Now, shall I surf around this one interface ( and leave it as it is or shall I give it a javadoc interface comment

[ May 28, 2005: Message edited by: Darya Akbari ]

Lara McCarver
Ranch Hand

Joined: Dec 09, 2003
Posts: 118
A software file is not a piece of literature. When you say that an interface should not be changed, it's OK to change the comments in it, the formatting and indentation, etc. You can even change the variable names. From a programming perspective, it is still going to compile into the same .class file, so it is the same.

Personally, I think the least you should do is change the Sun comments at the beginning of each method to Javadoc, because otherwise users of the class won't know how to use it, and since this is supposed to be the basic interface to your data, that's obviously a bad thing.

Although if it is really a big worry to you, you can probably leave it exactly as it came to you in your instructions, formatting and all, and explain in your choices.txt that you did that because of the do-not-modify instructions.
Reza Rahman
Ranch Hand

Joined: Feb 01, 2005
Posts: 580
I think most people have modified the comments without any penalty, so you should be fine.

Independent Consultant — Author, EJB 3 in Action — Expert Group Member, Java EE 6 and EJB 3.1
Darya Akbari
Ranch Hand

Joined: Aug 21, 2004
Posts: 1855
Ok, then the only two things I do is to indent the methods and javadoc method comments and to add a javadoc interface comment so people know what this interface is about.

It is sorta covered in the JavaRanch Style Guide.
subject: B&S: Javadoc in Sun's data interface allowed?
It's not a secret anymore!