Design Planning Specifications

Your first deliverable for this project is a design document, but this is simply the physical by-product of a more important process: design planning. Your planning should take place over the course of at least one group meeting, followed by a required meeting with your mentor. By the time you have completed the planning process, the design document should be trivial to write. This page describes not only the requirements of the design document, but also suggestions of how best to run your design planning meetings to come to a successful conclusion. Please read this entire document; if you just read the requirements for the design document, you may conduct your meetings in a counterproductive fashion.

I. The Design Document

A. Why create a design document?

1. The process of creating a design document helps assure that you've thoroughly planned your design before you start coding. That's an end in itself, since this is a software design class, but it will also help you code more efficiently, having an idea of how each piece of code you write will fit into your finished project.

2. Even if you do a lot of design planning ahead of time, not writing your plans down formally leaves you open to overlooking important elements of the program. You would only discover these oversights during the coding process, and then would have to code them on the fly, without the guidance of a global design plan.

3. Having a concrete design document allows you to refer back while you are coding, so that you can be sure everyone is writing code that works together properly to build up your final product. Without your plans to guide you, it is easy to lose the big ideas of your program during the straining process of coding each tiny element.

B. What are the requirements?

Your document must have four fundamental design sections, a use case section, and an extra section devoted to administrative details. In each section, justification is key! You must be able to defend every decision you make, so the document should include justifications of your design's most important features.

1. The design

a) The abstract: a 2- to 3-sentence, very high-level description of the structure of your program. You should not talk about classes, data types, or any other implementation details here; describe your program in terms of conceptual systems (as in, “the parser passes data to the processing pipeline, which takes inputs from the controller system...” and so on). This is the place for buzzwords: mention any and all of the following that apply:

i) The strategy you plan to use (e.g., a pipeline, an M-V-C structure, etc.)

ii) Interpretations you make of the data or problem you are expected to deal with, including generalizations, assumptions, and decisions regarding the representation of particular concepts

iii) Significant hierarchical details (e.g., “system A uses polymorphism to change behavior based on input type”)

iv) Significant data structure details (e.g., “internal state is maintained with a priority queue and a map”)

b) The summary: a 1-page description of the program at a slightly more specific and implementation-oriented level.

i) If necessary, describe the high-level interactions of the systems described in the abstract in more detail, if this level of detail wasn't appropriate for the abstract.

ii) List all the abstract/conceptual systems, and for each of them, describe implementation details:

· Each class you'll use

· What each class is called

· What purpose each class serves

c) The full description: as much text as you need, plus at least one diagram (it should be neat, but UML is not necessary), describing all classes in specific detail. The diagram and text should fully describe the relationships between all the classes, including polymorphism, encapsulation, data passing, and all interfaces. Furthermore, for each class, this section must describe its:

i) purpose

ii) responsibilities

iii) abilities/methods

iv) private data

You must justify and defend all significant details described in this section: why did you use an inheritance hierarchy here? Why are you using templates for this class? Why did you implement this class's private data as a linked list? Without essential questions like these answered, your design document is not complete.

d) The modification discussion: this section must discuss what properties of your design make your program easy to modify and extend. Back up your general discussion with a specific enumeration of all places in the program, as described in the full description above, that would need to be changed in order to add new variants of the functionality your program already has (e.g., new input methods, new conceptual classes of data, new algorithms).

2. The use case

This section should describe the behavior of your program, at a level of detail equal to that of the full description above, under at least one non-trivial use case. While you will probably be given a specific use case to describe, if you get to choose your own, it is best to think about one that exercises all elements of your program. Thus a good use case should cover a time in which significant changes in the program's internal state take place.

3. Administrative details

Your design document must also describe which group members will be working on what sections, and why the work is being parceled out in this way. Additionally, it must provide an estimate of the total amount of time your group expects the project will take, justified by giving estimates for individual portions of the program.

These requirements may seem daunting, but the fact is that a design document that meets them falls out with minimal effort from a properly conducted design planning group discussion.

II. The Design Meeting

The process of designing a program is an iterative one. In each pass through the process below, your group should refine the specificity of the discussion to build up and fill in the structure of the program. As in drawing a picture, you first start with a very loose, abstract idea of your finished project, then work in passes to give it more structure and detail. Keep in mind that this is a planning stage, so no non-trivial code should be written. Though the steps below are presented as discrete stages in the discussion, the design cycle proceeds very quickly, so they all happen more or less at once. Over time, the details of your program should fill in consistently across the entire design.

A. Pick an example—an appropriate use case, generalization, or characteristic of your program's problem domain—to motivate the discussion. Remember that extendability and flexibility of your program are part of the goal, so they should be included in this discussion.

B. Discuss the different ways that you can approach the example programmatically. Use diagrams to clarify this discussion; they most easily and straightforwardly describe how different parts of the program interact.

C. Describe technical details of the different approaches: general, abstract systems, classes and class hierarchies, interfaces, data structures, or methods, depending on the specificity of the discussion. Be sure to note responsibilities, internal data, and special properties (e.g., templatization, inheritance, etc.) of each detail. Remember that you must have a justification for every feature and decision! The entire group should work to scrutinize the design; the tighter the design is by the end of the planning process, the easier the coding will be later.

D. Return to the first step, picking a new example or expanding on the current one in such a way as to refine the scope of your discussion and challenge your current design.

Groups naturally develop their own vocabulary for discussing a problem. This leads to clear, descriptive names for systems, classes, and functions, which is an important element of good program design. Be sure to take the time to come up with good names, as they help organize your design and clarify the program's structure.

You know that your discussion has reached the proper level of refinement once the decisions your group makes can cover everything required in the design document; because of this, you should have all the information you need to write it up quickly. With a solid plan for your design in hand, your group can now take on the task of realizing it in code. Ultimately, the planning that you did beforehand should make this phase of the project much simpler, and make the ultimate product much better.