Design Document Guidelines

Overview

Describe your program here. You should provide enough detail that a human can understand what the program does. For example, if you are describing a game, you should state the mechanics of the game (is it a two person game? how do turns work?), the rules of the game, and winning conditions. What is the input to the program and what is its output?

Procedure

When the program’s main method is called, what does the program do? It is often easiest to start here, and then fill in the State and Methods parts as you write this section. But don’t feel like you need to write the Procedure, State, and Methods sections one after the other. Many expert programmers move back and forth between sections until they feel like their design is good enough.

Aim to make your procedure complete: a sufficiently motivated programmer should be able to simulate your entire program on paper using the information you supply in this document. Having enough information to simulate a design on paper is a mark of a good design document.

State

Describe each class you plan to use in this lab, and describe the set of values (instance variables) stored in each class. A class is like a “blueprint”: when we instantiate a class, Java “makes” the object that the blueprint describes. More practically, every object is a “box.” Java reserves space for an instantiated object, and this box can be used to store values. In your program, what values are stored in which objects?

Functional Requirements

What does your program do? Think of the set of methods on each class that move the program along. For example, in a game, we might have a displayBoard method that prints the board onto the screen. It is sometimes easier to think about your set of methods once you have started writing the procedure (below).

Here are some common methods we like to implement:

The constructor. This is the method that runs in order to initialize an object.
toString. This method asks an object to print something out. There are many uses for this. You might use it to generate a String that represents a board, or you might just use it to help debug your program. It’s up to you.
main. If your class serves as the entry point to your program, it needs a main method. The main method describes what happens when the user runs your program. It should call your constructor and then object methods.