Design Document

While the code ultimately determines how the program runs, it does not serve well to describe how the program is organized, what decisions were made while the program was constructed, or even the priorities of the project. Nor is code for large projects concise, so it does not allow new developers to quickly get an overview of the entire program. Thus, programs are often supplemented by documentation that serves to explain such fuzzy concepts. Successful programmers must be able to write about code at a variety of levels of detail in order to get their knowledge and ideas across.

Your design document should be organized in such way to allow another programmer to understand your program's design and organization so that they might evaluate it, debug it, or extend it. Your document should describe how your program is organized and why it was done that way. While you may assume your reader has a technical background, you may not assume that she has experience with this specific project or your design discussions.

It must include the following sections:

• Introduction
  This section describes the problem your team is trying to solve by writing this program (including extra credit variants you are interested in working on), the primary design goals of the project, and the primary architecture of the design. It should be approximately two or three paragraphs and discuss the program at a high-level (i.e., without referencing specific classes, data structures, or code).
• Overview
  This section serves as a map of your design for other programmers to gain a general understanding of how and why the program was divided up, and how the individual parts work together to provide the desired functionality. As such, it should describe specific modules in your project, their purpose with regards to the program's functionality, and how they collaborate with each other. A module may represent a single class or a group of classes related in some standard way, such as set of subclasses. It should also include a picture of how the modules are related (these pictures can be hand drawn and scanned in, created with a standard drawing program, or screen shots from a UML design program). This section should be approximately two pages and discuss specific classes, methods, and data structures, but not individual lines of code.
• User Interface Design
  This section describes how the user will interact with your program. It should describe the overall appearance of program's windows and how users interact with these windows (especially components specific to your program, i.e., means of input other than menus or toolbars). It should also include one or more pictures of the proposed user interface (these pictures can be hand drawn and scanned in, created with a standard drawing program, or screen shots from a dummy program that serves as a exemplar). Finally, it should describe any erroneous situations that are reported to the user (i.e., bad input data, empty data, etc.). This section may be as long as it needs to be and go into as much detail as necessary to cover all your team wants to say.
• Design Details
  This section describes each module introduced in the Overview in detail (as well as any other sub-modules that may be needed but are not significant to include in a high-level description of the program). It should describe how each module handles specific requirements given in the assignment handout, what resources it might use, how it collaborates with other modules, and how each could be extended to include additional requirements (from the assignment handout or discussed by your team). Finally, justify the decision to create each module with respect to the design's key goals, principles, and abstractions. This section may be as long as it needs to be and go into as much detail as necessary to cover all your team wants to say.
• Design Considerations
  This section describes the issues which need to be addressed or resolved before attempting to devise a complete design solution. It should include any design decisions that the group discussed at length (include pros and cons from all sides of the discussion) as well as any assumptions or dependencies regarding the program that impact the overall design. This section may be as long as it needs to be and go into as much detail as necessary to cover all your team wants to say.
• Remaining Issues
  This section should cover any known bugs that remain in the project's design or implementation. It is a chance for you to describe how you might fix the problem or refactor the design since you did not have time to actually change the code. This section may be as long as it needs to be and go into as much detail as necessary to cover all your team wants to say.
• Team Responsibilities
  This section describes the program modules each team member plans to take primary and secondary responsibility for and a high-level plan of how the team will complete the program.

Your document must include everybody's name that worked on the project, including outside people with whom you collaborated, and the date on which it was last updated.