Documentation Project

The purpose of this project is to give you experience in reading and
understanding code that you have not written and to give you practice in
writing useful documentation.

Logistics

This assignment is due at the beginning of class on 20 October. Please
turn this assignment in by bringing a paper copy to class on the 20th .
Because there are no classes on Monday, 13 October, there is neither a
laboratory meeting for nor a programming component to this project. In fact,
this assignment only asks you to read and understand code, not to run or
write it. We will, however, make the code for this assignment available
online so that you can run experiments on it if you wish.

This assignment involves a variant on the Calculator program that you
wrote in Laboratory 4.
As you did in that assignment, we have implemented code that runs the
"brains" of a Calculator. We have used the same Calculator interface that you
used in the problem set. (To run the Calculator with our new code, simply use
that code in place of your solution.)

Your assignment is to read through and understand the code that we have
written. You will discover that the code is completely undocumented. You will
demonstrate your understanding of the code to us by providing us with a
complete set of documentation for the ButtonHandler files. What you turn in
should be a complete set of documentation for the code that we have
written.

You may work closely with other students to understand the code in this
assignment. In fact, explaining the code to a friend is a good way to figure
out whether you understand it yourself. You can locate other students in the
class by mailing to the class list or zephyring to the class. (See the
general information handout for further details.) It may also be useful to
have someone read through your documentation just as you would have someone
proofread your paper.

You should, however, make certain that the documentation you turn in was
written entirely by you. You should also list anyone you discussed this
problem set with and briefly describe the nature of your interactions.

The Files

In order to do this assignment, you will need to read and understand the
following code files:

The only other files used to run this code are the Calculator interface
and the Main/GUI code that we provided for Laboratory 4. You do not need to
write documentation for those files.

If you want to compile and run these files, follow the instructions in the
file Readme.txt.

Understanding the Code

Execution of this code begins when a new ButtonHandler( Calculator
GUI) is created. What actually happens? Continue this way through the
code until you have defined all of the objects in the system. Then type a
button of the Calculator and follow through the execution of that code, too.
Don't forget to write down how the various fields of objects change.

You can figure all of this out using pictures, people, or the computer.
You may want to try several of these methods. Which ever approach you take,d
on't try to jump ahead, guessing what things will do. Instead, work slowly
and carefully through the code in a step by step manner. Continue
experimenting with the execution of this system of objects until you are
confident that you understand how it works.

You may want to begin by drawing pictures of the various kinds of objects
in this system. For example, you might take some index cards and put one
object on each. Draw the first ButtonHandler on an index card. List
its fields and the values assigned to each. If a field refers to another
object, you can write long squiggly lines to connect them, or you can be more
creative. For example, I like to glue in the pointer with a piece of string
or yarn. Alternately, you can simply assign each index card a unique
identifier and use that to refer to the object.

Alternately, you could get together with a group of friends and play-act
the changing of the objects. You may even want to do this in a classroom
where there's a big blackboard for scratch work. (This idea may sound silly,
but it is actually quite effective.

You can also modify the code, using System.out.println
statements, to show you what is going on at various points. This is
especially effective to check your understanding once you already think that
you know how the system works. Read the file Readme.txt for directions on how to compile and run the
code on Athena or in lab.

When you feel that you have an adequate understanding of what the code
does and of what the various pieces of the system do, you should begin to
work on your documentation.

The Assignment

What you will actually turn in is a set of documentation for this
software. The documentation that you provide comes in two parts.

The first part is documentation for the code itself. In documenting the
code, you should follow the conventions of the Design Project:

For each class, you should provide documetation indicating what role
instances of the class are supposed to play and how they are intended to
be used. You should describe the state of instances at the time that they
are created as well as how they are expected to evolve over time.

For each field, you should describe its purpose. You should also
include any relevant information about its initial state as well as
information about how it changes/is changed.

For each method or constructor, you should specify the argument and
return types as well as the relationship between them. You should also
list what the method does and, if it interacts with the object's fields
or other methods, detail these interactions.

For each line of code, you should include information as to how it
works, what it effects, why it exists, etc.

It should be possible to read your documentation and understand what the
code is doing -- and why -- almost without reading the code itself.

You may wish to edit the code files that we have provided directly, i.e.,
to write your documentation as comments in the file.

In additon to the documentation of the code, you should write an
overview/design document of 1-3 (typewritten) pages that describes how the
code works. This need not address the specific implementations of particular
methods, but instead should give a higher-level description of how the
various pieces of code interact. This document should, for example, include
sufficient information that it would be possible to figure out which piece(s)
of code to look at/modify if we wanted to add unary minus (negative numbers),
exponentiation, or some other functionality. (You should not explicitly
address these questions; this is just to give you a sense of the purpose of
this document.)

In writing up this documentation, you should answer the following
questions (among others):

What are the different types of objects in this system?

What components comprise these objects?

What actions can each of these objects take?

What goes inside, and what interactions occur between, these
objects?

Which of these objects are autonomous, i.e., self-animating?

What are the paths taken by these (and other) threads of control?

What you should turn in

You should turn in your documented code as well as the overall design
writeup. In addition, you should tell us about how you figured out what the
code does. You may include (descriptions of) any particularly useful props or
strategies.

You should, as always, include information on your collaborators and their
roles.