• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

nx:All of URLy Bird 1.1.3 about javadoc comments

 
liqun chang
Ranch Hand
Posts: 90
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi George:about the comments.
the instruction say

Documentation
The code itself should be as clear as possible; do not provide comments that do not add to the comprehensibility of the code. Awkward or complex code should have descriptive comments, and javadoc style comments must be used for each element of the public interface of each class. You must create a full suite of documentation for the classes of the completed project. This must be generated using the tool "javadoc" and must be in HTML format. Provide javadoc documentation for all classes you write.

the instruction also say:

package suncertify.db;
public interface DB
{
// Reads a record from the file. Returns an array where each
// element is a record value.
public String[] read(int recNo) throws RecordNotFoundException;
}


Whether i change it as follow:

package suncertify.db;
/**This DB interface for database file access.
*/
public interface DB
{
/** Reads a record from the file. Returns an array where each
element is a record value.
@return String[] represent the record.
@param recNo that represent the record Number.
@throws RecordNotFoundException when the record not exist or be deleted.
*/
public String[] read(int recNo) throws RecordNotFoundException;

My question is:whehter the comments of DB interface must be modified?
 
Jacques Bosch
Ranch Hand
Posts: 319
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Liqun.
I don't think they *must* be modified, but I think it is a good idea to reformat them according to javadoc standards.
Most people I know of modified the comments. I did, and I got full score for documentation.
Enjoy.
J
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Liqun,
Originally posted by liqun chang:
My question is:whehter the comments of DB interface must be modified?

I recommend modifying the form of the comments in the Sun-supplied interface so that they are in javadoc format. You are not changing the content of the comments, just putting them in to the javadoc format. Any assumptions the examiner makes about the Sun-supplied interface will still be true if you only modify the format of the comments. If you don't modify the comments of the Sun-supplied interface then that interface and it's methods will be missing from your javadoc documentation which I don't think is desirable given how important this interface is to the assignment.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic