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.
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.
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.
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.
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:
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):
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.
This course is a part of Lynn Andrea Stein's Rethinking CS101 project at the MIT AI Lab and the Department of Electrical Engineering and Computer Science at the Massachusetts Institute of Technology.
Last modified: Tue Oct 7 21:56:59 1997