SDSU CS 596: Client Server Programming
Design Document

[To Lecture Notes Index]
San Diego State University -- This page last updated May 12, 1995
----------

Design Documentation

The goal of the design documentation is to convey your design to other people. Normally, these other people will be programmers, who will build, modify, and/or maintain the program. (In this case it will be instructors who are grading your design and design document.) In either case, readers should be able to understand the design and be able to implement the design without having to spend a lot of time doing design work. If the document does that it is successful.

Some parts of the Document

Overview of Document

Since design documents can get big, an overview of the document can be important. This can be a small section that gives an overview of each section of the document. A table of contents is also very useful.

Requirements

You have been thinking about this problem for a while. However, this document may be the first time the implementation programmers learn about the problem. What is the problem that is being solved? What requirements must be met by the program? That includes what things must the program perform, resource requirements or restrictions, platform requirements, the setting the program be used in, and description of the target users.

Levels of Design Detail

A design documentation can include a list of function prototypes. A listing of hundreds of function prototypes will not be useful to a programmer trying to understand and implement your design. You need to provide an overview of high level description of your design. What are the major parts of the program, what does each do, how do they interact, how does data get from one location to another, and how does the program react to user actions? A high level description aids in understanding the overall design, but does not give much help in implementation.
You should provide a mid-level design. That is what are the modules in the system? Again what does each do, how do they interact, how does data get from one location to another? You are not required to provide a list of function prototypes. But, don't use this to hide major components of the program. The programmers will not be happy if you do this. Stating that you have a hash table module that allows you to add, find or delete items using strings as indexes does not require much more detail. Stating that you have a function that inputs a C program and returns the compiled program, needs more detail.
Diagrams can be useful to indicate the static and dynamic structure of the modules. That is a diagram showing how the modules interact. Class diagrams, flow diagrams, state diagrams, what ever helps the reader understand your design.

Protocol

This is a client server application. You should have a section describing the protocol. This means describing the commands that the client can send to the server and the responses the server can return. This includes what happens under error conditions.

Other Sections

This list is not meant to be all inclusive. What do you need to describe your design?

What to do with have problems you can't solve


If there are problems that you can't solve (or don't have time to solve), don't try to hide them. State them up front. In the real world the sooner management knows about problems the better. Hiding problems or omissions in an class assignment is not good either. If the grader finds the problem he assumes that either the student is stupid (did not know about the problem) or that the student thinks the grader is stupid (he will never find this). Neither is good for your grade.