Outline of Class 11: Documenting Your Java Programs
Held: Wednesday, February 4, 1998
- This Thursday at 4:15, selected math and CS faculty will be discussing
summer research opportunities. Come hear how you can get both money and
credit while participating in interesting projects.
- This Thursday at 7:30, Mike Jipping from Hope college will be speaking
on threads in Java. His talk is based in part on work done with
undergraduates as part of Hope's REU program.
- For more information on javadoc, see
- Like most modern programming languages, Java permits you to embed
comments into your programs. We've
- Comments are notes to the readers and users of your programs and
libraries. In general, they
are ignored by the compiler and interpreter (some weird languages
use comments to provide further information to programs as well as
people, but ...)
- Comments are read by programmers who have to understand/modify
your code. These programmers need to know what your
programs do and how they do it.
- Comments are read by programmers who have to use your code libraries
(even if they don't need to understand how they work). These
programmers care mostly about what your programs do (and
not how).
- Comments are read by normal people who want to execute
your programs. These people care about the instructions for
executing your program and the purpose of your program.
- There are therefore a number of types of comments to use in a program.
- All programs (or segments of programs, when appropraite),
should include a comment indicating the author of the program
the version of the program, and perhaps even the date the
program was created.
- Each class is usually preceded with a summary of the class.
- Often, groups of things (objects, classes, methods, whatever)
have an accompanying comment that describes overall implementation
strategy. I often call this the "reader's guide" to the program
(or portion thereof).
- Each variable is usually supplemented by a note as to the
use of the variable. Good variable naming can obviate this
need.
- Each "chunk" of code may be supplemented with a high-level
overview of the purpose of the code, e.g., "swap elements
in array"
- More complex / less readable pieces of code should be
supplemented with comments that explain their action
or activity.
- Each method is usually preceded with a summary of the purpose
of the function.
- Each method should also have a summary of pre- and post-
conditions. A precondition describes assumptions we make
before the code is executed. A postcondition describes
assumptions we make after the code is executed.
- Java provides three kinds of comments.
- Standard Java comments begin with
/* and
end with */. These comments are generally used
for programmers who must read or modify your code.
- "One liners" start with "//" and end with the end of the line.
This comments are generally used for programmers who must read
or modify your code.
- Javadoc comments begin with
/** and end with
*/. These comments are generally intended for those
who must use your code. The first Javadoc comment in a program may
also discuss how to execute your code.
- When writing programs, you should make sure to
- Write the "header" for each method or class before writing the method
or class.
- Write a "sketch" of your algorithm for each method before
writing the method.
- Add notes about particularly confusing code as soon after writing
the code as you can.
- We often write functions that can only operate correctly on a
subset of their potential arguments.
- For example, most square root functions only operate on
nonnegative numbers.
- Similarly, most sorting routines only work if the values to be
sorted can be compared.
- The restrictions on the arguments (and state of the object providing
the method) are called the preconditions to the method.
- When documenting your programs, you should make sure to clearly state
any preconditions your methods have.
- If you state preconditions, you
are only required to make sure that your program works correctly when
those preconditions are met.
- If your preconditions aren't met, you should throw an exception.
- To help the client who uses your methods, you should also document
everything you know to be true after a method successfully terminates.
These notes are called postconditions.
- What postconditions should you list? I recommend that you make it
a point to describe
- The primary intent of your method.
- Potential changes to other aspects of the system.
- Things that don't change (but that someone might think changes).
- These will become clearer as we develop our own descriptions of
data structures.
- Here's a sample set of pre- and post-conditions.
/**
* Sorts the elements of a subarray
*
* <br>pre: start ... end indicates a subarray of A
* <br>pre: the elements of A are comparable
* <br>post: the elements from start to end of A are in order
*/
public void sort(A,start,end)
throws IncomparableException