Granny's Programming Pearls
"inside of every large program is a small program struggling to get out"
JavaRanch.com/granny.jsp
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

some detailed questions on documentation

 
Gosling Gong
Ranch Hand
Posts: 51
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
cindy sung
Ranch Hand
Posts: 34
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic