File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
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
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "How to write comments?" Watch "How to write comments?" New topic

How to write comments?

Forrest Xu

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.
Mark Spritzler

Joined: Feb 05, 2001
Posts: 17276

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?

Perfect World Programming, LLC - iOS Apps
How to Ask Questions the Smart Way FAQ
I agree. Here's the link:
subject: How to write comments?
It's not a secret anymore!