Example of Documenting a Program Using Parameter Passing

The Situation:

You want to develop a program that can calculate and display the area of a circle, given its radius. Further, the program should be developed using top-down design so that it will consist of autonomous modules (functions in C++) that could be extracted and used in future programs that might require the same objectives.

TOP-DOWN ANALYSIS

This task can be sub-divided into smaller, simpler tasks called "modules". Such an approach is called top-down design. Each module is treated as a separate problem. In the C++ programming language, modules are written in separate blocks of code called functions, with a master function named "main" that calls (loads and executes) the other functions in whatever order is necessary to produce the overall objectives of the program.

An analyst's approach to top-down design can be illustrated in a form of documentation known as a structure diagram. The structure diagram below illustrates this top-down design approach. The diagram starts with a general task which is labeled and described in a box at the top, followed by more detailed descriptions on the levels below.

GLOBAL DOCUMENTATION

STRUCTURE DIAGRAM

Notice that each function appears in a box with a unique function identifier (label) at the top and a brief description of its purpose below. The description of purpose need not be as detailed as a problem statement, but must provide enough detail to identify the purpose of the function. Also notice the labels used to indicate the parameters (data being passed). These represent the actual parameters that are defined and used by the parent (top) function. Programmers may use different identifiers inside the child functions to represent the parameters, but should always show the actual parameters in the diagram to prevent any confusion that such differences might cause.

When separate functions are used, each function will be analyzed as a separate (simpler) program and documented accordingly. You should provide separate documentation for each function. This includes a Problem Statement, Data Definition (Sample Outputs, Symbolic Constant Lists, Variable Lists, etc.) and an Algorithm or Flowchart for each function. If data is to be passed between functions using formal parameters, then a Parameter List (see example below) should also be included for each function that receives data. The Desk Check is performed independently for each function and then overall for the main function.

The remainder of the documentation for this overall problem and its functions appears below.

SYMBOLIC CONSTANT LIST (GLOBAL):

DOCUMENTATION FOR FUNCTION "main"

PROBLEM STATEMENT

Request and store the radius of a circle and use it to calculate its area. Then identify and display that area. The program must allow for high precision floating point data.

SAMPLE OUTPUT (Softcopy)

In the sample output below, the numbers to the left of the sample screen are there only for your reference in other documentation. They are not intended to be part of the output. Bracketed text represents user input, not program output.

1
2
3
4
5

Circle Area Calculating Program

Enter the radius of the circle: [2.0]

The area of that circle is 12.566360

VARIABLE LIST

ALGORITHM

A. Start.
B. Call function DisplayTitle.
C. Assign RADIUS using value returned from function ReadRadius.
D. Assign AREA using value returned from function CircArea after passing it RADIUS and PI.
E. Call function DisplayArea passing it AREA.
F. End.

DESK CHECK

The desk check cannot be performed until all subordinate functions have been completed. Each function should be checked independently and then an overall check can be performed.

DOCUMENTATION FOR FUNCTION "DisplayTitle"

PROBLEM STATEMENT

Display the program title as shown in the sample softcopy on lines 1-2.

SAMPLE OUTPUT (Softcopy)

In the sample output below, the numbers to the left of the sample screen are there only for your reference in other documentation. They are not intended to be part of the output.

1
2

Circle Area Calculating Program

ALGORITHM

A. Start.
B. Display the program title as shown on line 1 of the sample softcopy.
C. Display a new line.
D. End.

DESK CHECK

Since this function involves no variables, there is no need for a Tracing Chart.

TEST OUTPUT (Softcopy)

1
2

Circle Area Calculating Program

DOCUMENTATION FOR FUNCTION "ReadRadius"

PROBLEM STATEMENT

Request and return the radius of a circle as a high precision floating point value.

SAMPLE OUTPUT (Softcopy)

In the sample output below, the numbers to the left of the sample screen are there only for your reference in other documentation. They are not intended to be part of the output. Bracketed text represents user input, not program output.

1

Enter the radius of the circle: [2.0]

(LOCAL) VARIABLE LIST

ALGORITHM

A. Start.
B. Prompt for the radius of a circle as shown on the sample softcopy.
C. Store the keyed-in response in R.
D. Return R to the parent function.
E. End.

DESK CHECK

TRACING CHART

TEST OUTPUT (Softcopy)

1

Enter the radius of the circle: [2.0]

DOCUMENTATION FOR FUNCTION "CircArea"

PROBLEM STATEMENT

Calculate and return the area of a circle using a passed-in radius and a passed-in value for Pi.

PARAMETER LIST

(LOCAL) VARIABLE LIST

ALGORITHM

A. Start.
B. Calculate and store A as P times R squared.
C. Return A to the parent function.
D. End.

DESK CHECK

TRACING CHART

Notice that the first two values (R and P) are shown on the same line. This is because they are both passed into the function together at the moment it is called. The remaining value is assigned during a subsequesnt step, so it is shown on a lower line in the Tracing Chart.

DOCUMENTATION FOR FUNCTION "DisplayArea"

PROBLEM STATEMENT

Display a blank line and then identify and display the passed-in area of a circle rounded to six places.

SAMPLE OUTPUT (Softcopy)

In the sample output below, the numbers to the left of the sample screen are there only for your reference in other documentation. They are not intended to be part of the output.

1
2

 
The area of that circle is 12.566360

PARAMETER LIST

ALGORITHM

A. Start.
B. Display a carriage return.
C. Display text identifying the area as shown on the sample softcopy (without carriage return).
D. Display the value of A rounded to six places followed by a carriage return.
E. End.

DESK CHECK

TRACING CHART

TEST OUTPUT (Softcopy)

In the sample output below, the numbers to the left of the sample screen are there only for your reference in other documentation. They are not intended to be part of the output.

1
2

 
The area of that circle is 12.566360

DESK CHECK FOR "main"

TRACING CHART

TEST OUTPUT (Softcopy)

In the sample output below, the numbers to the left of the sample screen are there only for your reference in other documentation. They are not intended to be part of the output. Bracketed text represents user input, not program output.

1
2
3
4
5

Circle Area Calculating Program

Enter the radius of the circle: [2.0]

The area of that circle is 12.566360

PROGRAM CODE (C++)

The C++ Language source code for this program can be view (with abundant commenting) on the web page about Parameter Passing in C++.