Design Documentation
General
Design documents serve two purposes. First, they aid others who may have an interest in the program. Your instructor, manager, co-workers, or even you yourself, should be able look over these documents to determine how your program is organized and for what purpose. Why would you need these documents? So that next month or next year, when you are required to add a feature or rewrite a section of the code, you can easily understand how the program is organized allowing you to quickly make the required changes.The second purpose for design documents involves you also. In order to solve anything more than the simplest of problems, you have to understand the problem and review the details of the solution to be sure you have the correct solution (and the correct problem!). Many times you will sit down to write a program or begin a project and the solution exists only in your mind. For most problems and for most of us, this is not good enough. Without writing anything down, we can only focus on one part of the problem at any one point in time. We can only get a vague feeling as to how the pieces fit together. To understand the problem and to be sure you have a viable solution, you need to sketch out at least a few details, including a statement of the problem, information on all of the input, information on all of the output, a function call diagram, and pseudocode for each expected function.
These are the minimum areas you should consider before starting a project or program. A more detailed description of these design items is given below.
Problem Statement
A problem is defined by The American Heritage Dictionary as "1. A question or situation that presents uncertainty or difficulty." In this section you should describe in your own words the situation that presents difficulty. At this point we are not concerned about the solution. Although we normally expect that there is a solution, there may in fact be no solution.In any case, your description here serves as a check to see if you really understand the problem. If you can not describe the problem, you do not understand it; if you do not understand the problem, you can not solve it. Be as detailed as possible without over-explaining. Be careful not to list the solution as the problem.
Input
List all expected input to the program. This may be input from the keyboard including menu choices and other types of data input. This may be input from a data file. List all the ways your program will obtain input.For each type of input, give enough examples to fully describe the range of each input.
Output
List all expected output to the program. This may be output to the screen such as menus, reports and error messages. This may be output to a data file. List all the ways your program can generate outputFor each type of output, give enough examples to fully describe the range of each output.
Function Call Diagram
Each programmer-defined function should be listed in a box. It's relationship to the other functions is indicated by a line drawn between the two boxes. If FuncA() calls FuncB(), a line is drawn between the two boxes to indicate this fact. On the diagram, FuncA() is placed further up than FuncB().+---------+This diagram will allow an individual to understand the structure and organization of the program at a glance. No programming logic is included in the diagram (it is NOT a flowchart).
| FuncA() |
+---------+
|
|
+---------+
| FuncB() |
+---------+Pseudocode
Write a detailed description in structured english to describe the logic behind each function in your program. Focus on the algorithm involved. How will you accomplish what needs to be done? What steps are needed? in which order?Avoid thinking in terms of any specific programming language. Separate the algorithm from the implementation of the algorithm. The purpose of pseudocode is to describe your solution to the problem (your algorithm) in some detail.
A function description should exist here for each box on the function call diagram.
The structured english should use one of the following types of flow control:
sequential statement (sum = sum + 1)Use indentation and white space to show membership.
decision statement (if x > 0 then y = 5)
iteration (loop)
function call (call FuncA())if x > 0 then
y = 5
increment sum by 1
else
z = 10
end ifConclusion
These five sections can provide an initial understanding of the problem and information for those who may have to look at your coded solution later (including yourself).
Development Guidelines
Code should be structured, organized, readable and well documented. In particular: Each source code file should have a file header located at the top of the file which contains the file name, your name, account, the due date and a list of related source code files. Example: //
// File name: cnode.cpp
//
// Written by: G. Andrus(andrus@cs.depaul.edu)
// Function names: CreateNode()
// Date Created: 1/09/96
// Last Modified: 1/10/96
// Related Files: inode.cpp, node.h
//If this is an assignment, make sure the assignment/program number and the class information is included in each file Each file should contain a comment header which contains a description of what is in the file. Choose a logical style of indentation and use it consistently. A few sample styles follow. (note the placement of braces) while() while() while() {
{ { // body
// body // body }
} }If a block, while or if construct takes more than a few lines, mark the end of the construct with an appropriate comment: e.g. // end of while (read) Generally speaking, each source code file should not be longer than two standard pages of code. Minimize the use of global variables. Keep functions short and simple. If necessary, rewrite a long function so it calls several shorter functions. Every function should have a header comment which describes the input parameters, output parameters, the action that the function takes (general narrative), and the return value (if any). Function header comments should have a section on constraints and assumptions. Note any special situations such as critical sections, modification of external variables and possible exception conditions. Use comments within the body of the function when necessary to make clear what each section of the function does. Reading the comments should be an alternative to reading the code, don't just parrot the code. For example: for(i=0;i<=100;++i)
{
sum += i;
}
Right: // Add all integers from 1 to 100
Wrong: // For i = 1 to 100, add i to 100Use clear, descriptive, mnemonic variable names. Not too short and not too long. Use a system that differentiates between constants, variables and functions/methods: constants (either constor #define) should beALL_CAPS variables should start with a Capital letter and each noun is capitalized: NumberOfEntries Functions and methods should start with a lower case and then use caps as above:getTotalNumberOfItems . Function arguments and braces should be aligned in the first column on the left. Function names start in the first column with the type, etc. on the preceding line int
main(int argc, char *argv[])
{
Revision History Version Date
Revision NoteAuthor 1.1 Apr. 1, 1998
Revised Document CreatedGary F. Andrus, CTI 2.1 Jan. 3, 2001
Merged from two other documentsDennis L. Mumaugh 3.1
Jan. 13, 2002
Merged Design Documention
with Development Guidlines
Dennis L. Mumaugh