Outline of Class 3: Constructors and Documentation

Miscellaneous

• I'd recommend that you regularly check the course news page. While I use it primarily for notes about updates to the web, it will occasionally contain other information (and the updates should also give you some more information about what's going on in the course).
• I've heard some well-warranted grumbling about my handwriting. Tell me when it's unreadable (or less than readable), and I'll work on making it more legible.
• I've heard some less-than-warrented grumbling about the engineering notebooks. Believe it or not, the notebook can help.
  • Note that it is important that you number pages in advance, and not remove or insert pages!
  • No, you do need not to put your class notes in this notebook. Your design notes and time log should suffice.
• Don't forget to ask me questions.
• For those of you interested in a more tutorial guide to Java, check out http://java.sun.com/docs/books/tutorial/index.html.
• Remember, I'm not yet used to Grinnell students, so please give me feedback as we go.
• Assignment 2 is now available. It is due next Wednesday.
• I've been told that the bookstore is out of some texts. Hopefully, they'll be ordering more. You should let them know if you need copies of any of the texts.

Constructors

• Along with creating new objects, we may need to initialize the objects (assigning values to particular fields, allocating new objects for some fields, etc.)
• Classes can include constructors that describe how to create such objects.
• Constructors can have parameters that are used in the initialization of the object.

• Constructors look very much like methods, with the difference that they have the same name as the class.
• Java is something of a polymorphic language: it permits you to define multiple methods or constructors with the same name, as long as they have different parameter types.
• This is particularly important for constructors, as there are many different ways that we may want to describe a new object.

• For our sample Complex class, we'll have three constructors:
  • A default constructor, with no parameters
  • A constructor used for converting doubles to complex numbers (so the imaginary part should be 0)
  • A constructor that takes both a real and imaginary part

       /**
        * Initialize to 0.0 + 0.0i
        */
       public Complex() {
         real_part = 0.0;
         imaginary_part = 0.0;
       } // Complex
       /**
        * Initialize to x + y*i
        */
       public Complex(double x,double y) {
         real_part = x;
         imaginary_part = y;
       }
       /**
        * Initialize to x + 0.0i
        */
       public Complex(double x) {
          real_part = x;
          imaginary_part = 0.0;
       }
    

• If you don't declare any constructors, Java uses a default constructor with no parameters.
• If you do declare constructors, that default constructors is no longer available.

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.

Methods

• In studying the basics of Java and the use of constructors, you've already seen most of what you need to know about methods.
• Each method has a name, a type, a parameter list, a body, and a number of optional components that we won't yet concern ourselves with.
• Object methods can refer to all the attributes of the object, as well as to other methods of the object.
• Class methods can only refer to class attributes and class methods (they can, of course, refer to object methods in conjunction with an object of the same class).

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.

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