Forums Register Login

Documentation Tips - Javadoc

+Pie Number of slices to send: Send
I found some things useful as I began checking over the comments in the supplied code. Since it is worth 20pts (as well as some points in General Considerations) I thought I would share my findings. First of all, let me mention that I used the DocCheck Utility available at http://java.sun.com/j2se/javadoc/doccheck/ to locate problems within the sourcecode. Though it is in beta and certainly not able to locate all errors, it was very good at finding things that I probably would have overlooked on my own.
Things that did come up frequently in the supplied code were the following:
1) Improper tag - Used @returns instead of @return
2) Improper usage - Used @param type name instead of @param name description (Within the description the type is usually specified.
3) Missing tags - omit @return
4) Improper names - Named parameter (in @param tag) doesn't match up with the actual name within the method declaration.
5) Missing commments altogether - all public classes/interfaces methods, and variables should have comments -- the supplied code, that I received, has missing comments.
Some of this probably goes without saying, but I found some of the errors within the comments particularly sneaky, that probably would have gone unnoticed without a more detailed look.
+Pie Number of slices to send: Send
Thx for the tip, Terry !
Popeye has his spinach. I have this tiny ad:
a bit of art, as a gift, the permaculture playing cards
https://gardener-gift.com


reply
reply
This thread has been viewed 525 times.
Similar Threads
Coding Standards
FBNS beginner.. help!!!
Submission Jar: test case + Ant build script
Documentation guidelines
Write good comments and produce good javadoc
More...

All times above are in ranch (not your local) time.
The current ranch time is
Mar 29, 2024 09:11:08.