| home page - news - syllabus - schedule - assignments - tutorials - tests - java - references - Mike Jacobson |
| basics - debugger (jdb) - testing framework (JUnit) - profiler (JRat) - documentation (javadoc) |
| Java Resources - Documentation Generation (javadoc) |
As is the case when other programming languages are used, inline documenetation can be used to include comments that aid in the reading, testing and maintenance of Java programs. Java also includes assertions that normally serve as comments but (through compilation of a program with the appropriate settings) can also be checked at runtime to test software. Finally, Java also includes a javadoc tool that can be used to generate HTML pages documenting your classes, and their data fields and methods.
In Java there are two ways to include comments in your code.
One way is to use the symbols // which denote the beginning of a comment: All text that follow these symbols until the end of the line are considered to be part of a comment.
Java also provides support for multi-line comments: Any text between the symbol pair /* and */ is considered to be a comment (which can take up several lines.
The above kinds of comments are useful for documenting significant parts of a method. For example, a multi-line comment can be used effectively to document a loop by specifying its loop invariant and loop variant.
You will see numerous examples of this use of comments in code throughout this course.
An assertion in Java has either the form
assert cond
or
assert cond : expn
where cond is a Boolean expression (that is, its value is either true or false) and expn is an expression with some value.
If assertion checking is disabled (which is the case if you run your program without using settings to enable it) then an assertion serves as another kind of comment: cond is a condition that is supposed to be satisfied. For example, this might be part of a method’s precondition if the assertion appears at the beginning of the method, or it might be part of a loop invariant if it appears at the beginning of the body of a loop.
On the other hand, if your program is run with assertion assertion checking enabled, then the Boolean expression cond is evaluated whenever the assertion is reached. If the expression’s value is true (as expected) and (as should be the case) the evalation of this expression has no side effects, then computation proceeds just as it would be if assertion checking was disabled. On the other hand, if the expression’s value is false then an AssertionError is thrown (and computation proceeds in the way one would expect when an exception is raised and not caught).
If the first, simpler form of the assert statement is used then a generic message is displayed if the cond is false and an AssertionError is raised. A more detailed message is provided if the second form of the assert statement is used; indeed, the expn is used to generate a string that is included as part of the error message.
Since assertions are either used as documentation or for testing of code it is not necssary or recommended for any AssertionError to be caught.
Additional information about assertions is available as part of Sun’s online Java documentation of Java 6. They are mentioned, but not discussed in any detail, in the textbook.
Note: Significantly older versions of Java included an “Assert” class. This was replaced by the assert statement described above, so Assert (with a capital A) should no longer be used.
Java provides a standard format for writing comments and documenting classes. If this format is used the javadoc tool can be used to produce HTML pages (resembling Sun’s pages that describe Java’s packages and classes).
A short introduction to Java’s documentation style for classes and methods, and the use of the javadoc tool, can be found on pages 723–725 in Appendix A of the text. Considerably more information about how to write comments for the javadoc tool and, more generally, about the javadoc tool and its use is available as part of Sun’s online Java documentation.
|
Last updated:
http://www.cpsc.ucalgary.ca/~jacobs/cpsc331/F10/java/javadoc.html |