Class 13: Documentation and Testing

Held Monday, February 15

Summary

• Documentation and Javadoc
• Testing: why and how
• Preconditions and postconditions
• A sequence class

Contents

Handouts

• Portions of Chapter 4 of Java Plus Data Structures
  • Somewhat less polished than they might otherwise be; I'll still take suggestions.
• 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.

Notes

• 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 Assignment 5?
• 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.

Documentation

• Each class you create must be understood by a number of different people,
  • 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.

Javadoc

• 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
  • http://java.sun.com/products/jdk/javadoc/writingdoccomments.html
  • http://www.math.grin.edu/~rebelsky/jdk1.1.3/docs/tooldocs/solaris/javadoc.html
  • http://java.sun.com/docs/books/jls/html/18.doc.html
• 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
  • @author
  • @version
  • @see
  • @version
  • @param
  • @return
  • @exception
• 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,

Short Lab: Javadoc

We'll spend about fifteen minutes on the Javadoc Lab.

Commenting Your Programs

• 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 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 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 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.

Preconditions and Postconditions

• 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. (Pretty cool!)
• If your preconditions aren't met, you might consider throwing an exception.
  • 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 data structures.
• 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) 
    throws IncomparableException
  

History

• 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 CSC152 98S.