Fundamentals of Computer Science II (CSC-152 97F)
Outline of Class 6: Documentation
- 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
- 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
(this goes before the class declaration)
- Compile all the files
javac PingPong.java Player.java ...)
- Run the interpreter on the class with the appropriate
- 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
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.
- Those of you accustomed to working in languages like Pascal and
C may wonder what command you use to delete the objects you create
- 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
- 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
method with each class.
- The method must be named
finalize, have no parameters,
and be of type
- 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
- 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. 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
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
- 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
- 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
- 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
and you can create a symbolic link to that directory.
- 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
method that tells you how many we've created.
- 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.
- Add a
finalize() method to your
that notes when an object is destroyed. See if you can get the
method to execute (other than calling it explicitly).
- Try documenting our
Complex class and then running
javadoc to see the results.
Disclaimer Often, these pages were created "on the fly" with little, if any, proofreading. Any or all of the information on the pages may be incorrect. Please contact me if you notice errors.
Source text last modified Wed Nov 5 12:36:20 1997.
This page generated on Wed Nov 5 12:38:49 1997 by SiteWeaver.
Contact our webmaster at firstname.lastname@example.org