aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes some detailed questions on documentation 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 "some detailed questions on documentation" Watch "some detailed questions on documentation" New topic
Author

some detailed questions on documentation

Gosling Gong
Ranch Hand

Joined: Jun 20, 2002
Posts: 51
Hello, everyone!
I have some detailed questions on documentations,
1. should I put JavaDoc comments on private methods and instance variable?
2. what kind of comments did you put for the code? which should I use // or /* */?
3. shoule I comment on the deprecated methods, or only just need to delete the old one?
4. how did you make the javaDoc comments on the DataInterface, just copy it from Data and no comments on the LocalData and RemoteData?
5. continue with item 4, if i use LockManager, there is also lock method, should I comment it the same as Data?
6. How to comment a method which is composed by some other methods, for example,
public void lock(int recno) {
if(recno == -1) lockDatabase();
else lockRecord();
}
because the functional descriptions are already in the lockDatabase() and lockRecord, if I comment them again in the lock, is that redundant?
7. Did you modify the comments in Data class which has some obvious comment error, for ext.,
in lock comment, there is @param recno, but the actual argument for lock is lock(int record).
8. if I don't implement lock/unlock in the Data class, leaving the methods empty, should I change the JavaDoc comments that already there, or just don't care?
sorry for bring up so many trivial questions, but I think it is a good chance for us to learn documentation.
thanks!
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17259
    
    6

1. Yes or no. You decide. I like having the private methods and private instance variables javadoc'd, but you don't have to. public instance variables do need to be javadoc'd
2. use // for a single line and /* for multiline comments.
3. I'd comment the change you made.
4. I made my own docs for the interface, they don't exactly match the data class, and no comments on the implementing classes.
5. Doesn't it have a different signature? it should, and I think you should make a seperate commetn in the LockManager.
6. That is redundant. Not needed.
7. Hey, I never caught that. You can change it.
8. I don't remember what the origianl commetns where for the Data.lock method, I would change it and write that you don't implement it, that LockManager handles locks for the data for you.
Mark


Perfect World Programming, LLC - Two Laptop Bag - Tube Organizer
How to Ask Questions the Smart Way FAQ
cindy sung
Ranch Hand

Joined: Jul 02, 2002
Posts: 34
Hi,
In the instruction, it says:
You will not be marked on the choice that you made, but rather on the consistency of your decision making process

Can somebody tell me how I can express my 'consistency of decision making process' to the
assessor?
Thanks.
cindy


SCJP2; SCJD2;
 
jQuery in Action, 2nd edition
 
subject: some detailed questions on documentation