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.