• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

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

 
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 ]
 
Ranch Hand
Posts: 118
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
author
Posts: 580
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
reply
    Bookmark Topic Watch Topic
  • New Topic