How to write comments?

[Forrest Xu]

Hi all,
I have some problem about writing comments in source code. Please see:
1. version. the assignment version is @version 1.1. how about updated class version? how about new class' version? Do I need tell Sun what vesion the new version is based on? How to do it.
2. I does not changes lock method in Data class.
how to write the comments for it. can I write something like following words?
/**
* This method in Data object will not be called in this assignment. Keeps
* it unchanged.
*
* @param recno The record number to lock.
* @exception IOException If the record position is invalid.
*/
3. deprecated method comments in
private synchronized String[] readRecord() throws IOException.
can I write something like following words?

/**
* Reads a record from the current cursor position of the underlying random
* access file. version 1.1 uses
* rv[i] = new String(buffer, 0, offset, description[i].getLength();
* It is deprecated method that uses the platform's default encoding. Uses
* rv[i] = new String(buffer, offset, description[i].getLength());
* to construct a new String by converting the specified subarray of buffer
* using the platform's default character encoding.
*
* @return The array of strings that make up a database record.
* @exception IOException Generated if the RandomAccessFile cannot read from
* the database file.
*/
4. Does the design choice need to be added in the comments? Where is the best place, Class comments or methods comments?
Please help me!
Thanks in advance.
Java2de

[Mark Spritzler]

Design choices don't need to be in the JavaDoc comments. A good explaination that describes the method is needed. Think of it this way, If you we a new programmer looking at your code as if someone else wrote it, and you were looking at the API Docs, which JavaDoc creates. What would you like to see there? What would help you to understand better what that class or method does?
Mark