• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

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

 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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

Regards,
Darya
[ May 28, 2005: Message edited by: Darya Akbari ]
 
Lara McCarver
Ranch Hand
Posts: 118
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
author
Ranch Hand
Posts: 580
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think most people have modified the comments without any penalty, so you should be fine.
 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.

Regards,
Darya
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic