Outline of Class 6: Documentation

Miscellaneous

• For those of you interested in other issues in CS, there is a weekly Monday brown-bag-lunch in a room whose number I forget. The schedule and location are posted around the department.
• As per normal, I've rearranged the syllabus slightly.
• The textbook is now in the bookstore. I'd like you to read chapter 2 as soon as you can.
• Some of you have asked about how best to deal with multiple classes. Here's the basic strategy:
  • Put each class in a separate file
  • In any class that refers to another class, begin the file with import OtherClass; (this goes before the class declaration)
  • Compile all the files (with javac PingPong.java Player.java ...)
  • Run the interpreter on the class with the appropriate main() method.
• I will do my best to be available Wednesday evenings, from approximately 8-10:30 pm. After this week, assignments will be due on Thursdays so that you can make use of my advice in the evening.
• To make up for my limited evening presence (and overall limited time this term), I'll be hosting Sunday evening dinners from 6-8pm. I won't guarantee gourmet food, but each meal will be home-cooked. Some weeks, it will just be William and I (and any of you who come), other weeks my wife or other friends or family may be there. I can probably handle four people per week, so email me with a week or two you'd like to come, and any dietary restrictions/preferences. You are not required to attend Sunday evening dinners.

Finalizers

• Those of you accustomed to working in languages like Pascal and C may wonder what command you use to delete the objects you create with new.
• Surprisingly, in Java you do not have to delete objects. Rather, a garbage collector identifies the objects that are no longer being used, and automatically reclaims the memory associated with them.
• Because there are times that you would like to do something special when an object is destroyed (e.g., close an open file associated with the object), Java permits you to associate a finalize method with each class.
• The method must be named finalize, have no parameters, and be of type void.

Documenting Your Programs

• Like most modern programming languages, Java permits you to embed comments into your programs.
• Comments are notes to the reader of your program. 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 ...)
• There are 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. For example,

     /**
      * sorts the elements of a subarray
      *
      * pre: start ... end indicates a subarray of A
      * pre: the elements of A are comparable
      * post: the elements from start to end of A are in order
      */
    public void sort(A,start,end)
    

• Java provides two kinds of comments.
  • Standard Java comments begin with /* and end with */
  • "One liners" start with "//" and end with the end of the line

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

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
    * ...
    */
  

• Yes, you have some freedom with whitespace. The important thing is to begin the comment with two stars.
• 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, I've placed them in ~rebelsky/pub/javadoc.images, and you can create a symbolic link to that directory.

Exercises

Constructors

• Extend the Complex class with the constructors given in the previous class and test the use of the constructors.
• Add a created class attribute that keeps track of how many complex numbers we've created, and a howMany() class method that tells you how many we've created.

Methods

• Add an add(Complex c) method that adds another complex number to the current complex number, creating a new complex number. Note that you'll need to use new Complex() to create the new number. Test the use of the new constructor.

Finalizers

• Add a finalize() method to your Complex class that notes when an object is destroyed. See if you can get the method to execute (other than calling it explicitly).

Documentation

• Try documenting our Complex class and then running javadoc to see the results.