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.