Comments

Comments

• Each part of your program should be introduced by a comment that indicates its purpose, semantics, and use. Early in the course, we will explore the JavaDoc system that promotes this kind of documentation.
  • A class (or program) is normally in a separate file, unless it is an "inner class." It should begin with a comment that states who wrote the code, when, and why. This is the place to advertise any special features of your code. Be sure to use @author and @version javadoc tags.
  • Each method should be preceded with a comment that tells what the method does, what each parameter signifies, and what value (if any) is returned. Use @param, @return, and @throws as appropriate.

    Pre and post-conditions should be included in the comments for a method. The @return tag will normally include the postcondition in cases where the method returns a value. Preconditions for public methods should be checked at the beginning of a method, with an appropriate exception thrown if the precondition failed. Preconditions for private methods can be checked using an assert statement as their failure indicates an error by the programmer of the class, making it hard to recover from the error dynamically. Post-conditions are typically also checked via an assert statement, whether the method is public or private. If evaluating the assert statement is too expensive (e.g., essentially involves re-executing the method) then the assert statement may be omitted.

  • Each variable, or block of closely related variables, should have a comment indicating the purpose of the variable.
• Avoid over-commenting. If there are sufficient general comments, as discussed above, then line-by-line comments will often be unnecessary. In particular, avoid useless comments like the one below.

  n = n + 1 // add one to n

• Comments should go above the code or, in the case of very short comments, to the right. Always put a blank line before a comment. Indent comments by the same amount as the code.
• As you are developing and testing a program, it is often useful to "comment out" blocks of code. But the code you submit should have no such comments.
• Comments on variables and methods should be entered when the code is first typed in. This will make it much easier for you and the instructor or TA to figure out what your program is actually doing versus what you think it may be doing.

Comments