wood burning stoves 2.0*
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 Android Security Essentials Live Lessons this week in the Android 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 (DB.java). 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 (DB.java) 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.

I agree. Here's the link: http://aspose.com/file-tools
subject: B&S: Javadoc in Sun's data interface allowed?
Similar Threads
B&S: What types do you comment with javadoc?
Elegant solution to waiting without CPU activity?
B&S: Handling different data files (format, schema)?
NX: UrlyBird database design question
NX: Bodgitt and Scarper: may I modify the javadoc of the interface DB.java?