• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

NX: Specs on code commenting

 
Paul Tongyoo
Ranch Hand
Posts: 91
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all-- I had a couple of questions on code commenting.
Our specs say that we need to comment every member of the public interface to our classes, but elsewhere it says that you need documentation for all classes. I see a descrepency here; what if you have a class with all protected members? I'm taking the safe route and documenting all my class members, regardless of access level. Is this bad?
Also, the specs say "do not provide comments that do not add to the comprehensibility of the code.". So should we not comment our public getter and setter methods? Or what about other very simple public methods (I have an inner class constructor with one code statement in its body)? I am seeing a contradiction to the rule mentioned in my first paragraph.
What commenting standard is the best (safest) route to follow?
Thanks in advance,
Paul
[ November 05, 2003: Message edited by: Paul Tongyoo ]
[ November 05, 2003: Message edited by: Paul Tongyoo ]
 
S Perreault
Ranch Hand
Posts: 37
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Paul Tongyoo:
[QB]Hi all-- I had a couple of questions on code commenting.
Also, the specs say "do not provide comments that do not add to the comprehensibility of the code.". [QB]

Hello Paul,
Although I have been wondering about the first question, I believe that this part is talking about comments inside the methods, not outside them.
If you have a relatively difficult to understand piece of code inside a method, you should provide comments to describe why you are doing it and what it does.
I hope this is correct!
Perogi.
 
Paul Tongyoo
Ranch Hand
Posts: 91
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by S Perreault:

...
Although I have been wondering about the first question, I believe that this part is talking about comments inside the methods, not outside them.
...


If this is indeed correct then I am relieved - because that's what i'm currently doing!
To add more thoughts to my first question, it seems maybe redundancy is in fact allowed in interface commenting; i've been browsing the javadocs for the J2SE API and they're allowing for it (to a certain extent).
Paul
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Paul & Perogi,
I had javadoc comments for everything that could have a javadoc comment, including private variables and methods. My reasoning was that (a) if someone really wanted to, then they could generate the javadoc at whatever level they wanted - there would never be a level at which the javadoc wouldn't work; and (b) a programmer maintaining my code can still read the javadoc comments if they were working in the method, so it would still be useful to them.
This certainly didn't cost me any marks
As for comments within the methods themselves - I did use them, but not very often. Most times I let the code speak for itself.
Regards, Andrew
 
Paul Tongyoo
Ranch Hand
Posts: 91
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Andrew!
One more question -- did you submit javadocs that showed the doc comments for all access levels or a subset of levels?
[ November 05, 2003: Message edited by: Paul Tongyoo ]
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Paul.
I just used the default level of javadoc commands for my submission.
Regards, Andrew
 
Paul Tongyoo
Ranch Hand
Posts: 91
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Andrew Monkhouse:
Hi Paul.
I just used the default level of javadoc commands for my submission.
Regards, Andrew


Ok, the default level for javadoc is "protected/public", which doesn't produce javadocs for package-level classes. So did the actual HTML javadocs you submitted to Sun just include your public/protected classes (the number of which is significantly smaller than your total system classes because of reasons you mentioned in our access level discussion)?
Sorry to drag out this thread!
Paul
[ November 06, 2003: Message edited by: Paul Tongyoo ]
[ November 06, 2003: Message edited by: Paul Tongyoo ]
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Paul,
Originally posted by Paul Tongyoo:
So did the actual HTML javadocs you submitted to Sun just include your public/protected classes (the number of which is significantly smaller than your total system classes because of reasons you mentioned in our access level discussion)?

Correct - my submitted HTML javadoc only contained public/protected classes.
But, as mentioned before, if the examiner really wanted to, then they could have run javadoc on my code themselves, and seen the javadoc for all classes, methods, and variables.
Regards, Andrew
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic