This week's giveaway is in the Android forum.
We're giving away four copies of Android Security Essentials Live Lessons and have Godfrey Nolan on-line!
See this thread for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes How to write comments? 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 "How to write comments?" Watch "How to write comments?" New topic
Author

How to write comments?

Forrest Xu
Greenhorn

Joined: Jan 30, 2002
Posts: 26
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
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17249
    
    6

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


Perfect World Programming, LLC - Two Laptop Bag - Tube Organizer
How to Ask Questions the Smart Way FAQ
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: How to write comments?
 
Similar Threads
Deprecated Methods ?
deprecated methods
suncertify.db.Data
getBytes Deprecated Method
Data: Unexpected database access problem