Class 13: Documentation and Testing
Held Monday, February 15
- Documentation and Javadoc
- Testing: why and how
- Preconditions and postconditions
- A sequence class
- Portions of Chapter 4 of
- Somewhat less polished than they might otherwise be; I'll still
- Javadoc Lab
- Evaluation form for lab manual. Get a point (not a unit) of extra
credit for filling it out and turning it in to Rachel.
- Assignment 3 returned.
- In following with the math tradition of only grading parts of
an assignment, I only graded one of your classes (the
Circle class), although I scanned the others.
- You need to be more careful about using standard commenting styles
(today we'll learn why).
- You need to be more careful about indenting.
- Are there questions on
Assignment 4 or
- A set of notes on this assignment will be available later today or
before class tomorrow. We'll talk about the assignment tomorrow, when
I hope to have some of the late homeworks graded.
- Thursday at 4:15 is a cool statistics talk.
- Each class you create must be understood by a number of different
- Clients who use the class in their programs;
- Clients who extend the class to create their own classes;
- Clients who maintain your class; and
- Teachers who grade your class.
- At times, you will serve in each of these roles. And, if you've
ever tried to look at code that's a few months old, it's as if you're
a different person.
- How do you support all of these people? Clearly, they shouldn't
have to read your code, since few humans like to read ``raw Java''.
- Traditionally, you write documentation for the different
people who care about your programs.
- What are some examples of the documentation you might prepare for
each kind of reader of your code.
- Obviously, a lot of information is shared between the different kinds
of documentation (and between the documentation and the code).
- To help programmers generate documentation, and to encourage them
to include in-code comments, Java provides a utility, Javadoc,
that turns particular kinds of in-code comments to readable files.
- Java provides a simple program,
javadoc, that can
build HTML documentation from your Java code, especially if you
follow a particular commenting style.
- Some online documentation for javadoc can be found at
- You should include javadoc comments for your objects and methods.
- The basic form of a javadoc comment is
* Here's the comment
* @author Your name
* @version 1.0
- The comments can include HTML tags.
- The lines preceded by at-signs are special tags.
- Special tags include
- The HTML files that are generated load images from the subdirectory
images. While I can't find the piece of the
javadoc documentation the specifies where to find those images,
We'll spend about fifteen minutes on the
- Like most modern programming languages, Java permits you to embed
comments into your programs. You've seen me use a number
of commenting styles in my programs.
- 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
- 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 appropriate),
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
- Each ``chunk'' of code may be supplemented with a high-level
overview of the purpose of the code, e.g., ``swap elements
- More complex / less readable pieces of code should be
supplemented with comments that explain their action
- 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
*/. 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
- 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
- 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. (Pretty cool!)
- If your preconditions aren't met, you might consider throwing an
- Some designers believe that exceptions should be limited to
exceptional cases not described in the preconditions.
- 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
- Here's a sample set of preconditions and postconditions.
* 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)
- Created Monday, January 11, 1999.
- Added short summary on Friday, January 22, 1999.
- Added content on Monday, February 15, 1999. Much of this content
was based on
outline 11 and
outline 12 from