Quote:
Originally Posted by basicxman
EDIT: On the note of quite a few of WPILib's function comments, I find them lacking in actually useful documentation. A lot of them generally take the name of the function, and expand it to a grammatically correct English sentence instead of saying something useful like for instance, the unit of the return value (off the top of my head).
|
Amen to that. I've noticed a trend of people thinking that javadoc comments are the same as documentation. Unless you're extremely verbose in your comments they aren't. Javdoc is a neat concept, but in most of the cases I've seen it only serves as about half of what is really needed in the way of documentation.
Whatever your personal philosophy is on commenting, you should try to remember that you aren't writing them for professional programmers, you're writing them for high school students who may or may not have a knowledgeable mentor to guide them in the future. Your code and comments should be clear as day so that someone just starting out can tell what you were doing and why.