Design Programs

The preceding sections show that the development oI a program requires many steps. We
need to determine what's relevant in the problem statement and what we can ignore. We
need to understand what the program consumes, what it produces, and how it relates
inputs to outputs. We must know, or Iind out, whether Scheme provides certain basic
operations Ior the data that our program is to process. II not, we might have to develop
auxiliary programs that implement these operations. Finally, once we have a program, we
must check whether it actually perIorms the intended computation. This might reveal
syntax errors, run-time problems, or even logical errors.
To bring some order to this apparent chaos, it is best to set up and to Iollow a DESIGN
RECIPE, that is, a step-by-step prescription oI what we should do and the order
9
in which
we should do things. Based on what we have experienced thus Iar, the development oI a
program requires at least the Iollowing Iour activities:
;; Contract: area-of-ring : number number - number

;; Purpose: to compute the area of a ring whose radius is
;; outer and whose hole has a radius of inner

;; Example: (area-of-ring 5 3) should produce 50.24

;; Definition: refines the header,
(define (area-of-ring outer inner)
(- (area-of-disk outer)
(area-of-disk inner)))

;; Tests:
(area-of-ring 5 3)
;; expected value
50.24
Figure 3: The design recipe: A complete example


Understanding the Program's Purpose:
The goal oI designing a program is to create a mechanism that consumes and
produces data. We thereIore start every program development by giving the
program a meaningIul name and by stating what kind oI inIormation it consumes
and produces. We call this a CONTRACT.
Here is how we write down a contract Ior area-of-ring, one oI our Iirst
programs:
10

;; area-of-ring : number number - number
The semicolons indicate that this line is a COMMENT. The contract consists oI two
parts. The Iirst, to the leIt oI the colon, states the program's name. The second, to
the right oI the colon, speciIies what kind oI data the program consumes and what
it produces; the inputs are separated Irom the output by an arrow.
Once we have a contract, we can add the HEADER. It restates the program's name
and gives each input a distinct name. These names are (algebraic) variables and
are reIerred to as the program's PARAMETERS.
11

Let's take a look at the contract and header Ior area-of-ring:
;; area-of-ring : number number - number
(define (area-of-ring outer inner) ...)
It says that we will reIer to the Iirst input as outer and the second one as inner.
Finally, using the contract and the parameters, we should Iormulate a short
PURPOSE STATEMENT Ior the program, that is, a brieI comment oI what the
program is to compute. For most oI our programs, one or two lines will suIIice; as
we develop larger and larger programs, we may need to add more inIormation to
explain a program's purpose.
Here is the complete starting-point Ior our running example:
;; area-of-ring : number number - number
;; to compute the area of a ring whose radius is
;; outer and whose hole has a radius of inner
(define (area-of-ring outer inner) ...)
ints: II the problem statement provides a mathematical Iormula, the number oI
distinct variables in the Iormula suggests how many inputs the program
consumes.
For other word problems, we must inspect the problem to separate the given Iacts
Irom what is to be computed. II a given is a Iixed number, it shows up in the
program. II it is an unknown number that is to be Iixed by someone else later, it is
an input. The question (or the imperative) in the problem statement suggests a
name Ior the program.
Program Examples:
To gain a better understanding oI what the program should compute, we make up
examples oI inputs and determine what the output should be. For example, area-
of-ring should produce 50.24 Ior the inputs 5 and 3, because it is the diIIerence
between the area oI the outer disk and the area oI the inner disk.
We add examples to the purpose statement:
;; area-of-ring : number number - number
;; to compute the area of a ring whose radius is
;; outer and whose hole has a radius of inner
;; example: (area-of-ring 5 3) should produce 50.24
(define (area-of-ring outer inner) ...)
Making up examples -- -efore we write down the program's -ody -- helps in
many ways. First, it is the only sure way to discover logical errors with testing. II
we use the Iinished program to make up examples, we are tempted to trust the
program because it is so much easier to run the program than to predict what it
does. Second, examples Iorce us to think through the computational process,
which, Ior the complicated cases we will encounter later, is critical to the
development oI the Iunction body. Finally, examples illustrate the inIormal prose
oI a purpose statement. Future readers oI the program, such as teachers,
colleagues, or buyers, greatly appreciate illustrations oI abstract concepts.
The Body:
Finally, we must Iormulate the program's body. That is, we must replace the
``'' in our header with an expression. The expression computes the answer
Irom the parameters, using Scheme's basic operations and Scheme programs that
we already defined or intend to define.
We can only Iormulate the program's body iI we understand how the program
computes the output Irom the given inputs. II the input-output relationship is
given as a mathematical Iormula, we just translate mathematics into Scheme. II,
instead, we are given a word problem, we must craIt the expression careIully. To
this end, it is helpIul to revisit the examples Irom the second step and to
understand how we computed the outputs Ior speciIic inputs.
In our running example, the computational task was given via an inIormally stated
Iormula that reused area-of-disk, a previously defined program. Here is the
translation into Scheme:
(define (area-of-ring outer inner)
(- (area-of-disk outer)
(area-of-disk inner)))
Testing:
AIter we have completed the program deIinition, we must still test the program.
At a minimum, we should ensure that the program computes the expected outputs
Ior the program examples. To Iacilitate testing, we may wish to add the examples
to the bottom oI the Definitions window as iI they were equations. Then, when
we click the Execute button, they are evaluated, and we see whether the program
works properly on them.
Testing cannot show that a program produces the correct outputs Ior all possible
inputs -- because there are typically an inIinite number oI possible inputs. But
testing can reveal syntax errors, run-time problems, and logical mistakes.
For Iaulty outputs, we must pay special attention to our program examples. It is
possible that the examples are wrong; that the program contains a logical mistake;
or that both the examples and the program are wrong. In either case, we may have
to step through the entire program development again.
Figure 3 shows what we get aIter we have developed the program according to our
recipe. Figure 4 summarizes the recipe in tabular Iorm. It should be consulted whenever
we design a program.
Phase Goal

Activity
Contract
Purpose and
Header

to name the
Iunction;
to speciIy its
classes oI
input data
and its
class oI
output data;
to describe its
purpose;
to Iormulate a
header
choose a 3ame that Iits the problem study the problem
Ior clues on how many unknown ``givens'' the Iunction
consumes pick one variable per input; iI possible, use
names that are mentioned Ior the ``givens'' in the
problem statement describe what the Iunction should
produce using the chosen variables names Iormulate
the contract and header:
;; 3ame : 3:mber ...--~ 3:mber
;; to compute ... Irom ...
(define (3ame ) ...)
Examples

to characterize
the input-
output
relationship
via examples
search the problem statement Ior examples work
through the examples validate the results, iI possible
make up examples
Body

to deIine the
Iunction
Iormulate how the Iunction computes its results
develop a Scheme expression that uses Scheme's
primitive operations, other Iunctions, and the variables
translate the mathematical expressions in the problem
statement, when available
Test to discover
mistakes
(``typos'' and
logic)
apply the Iunction to the inputs oI the examples check
that the outputs are as predicted



Figure 4: The design recipe at a glance


The design recipe is not a magic bullet Ior the problems we encounter during the design
oI a program. It provides some guidance Ior a process that can oIten appear to be
overwhelming. The most creative and most diIIicult step in our recipe concerns the
design oI the program's body. At this point, it relies heavily on our ability to read and
understand written material, on our ability to extract mathematical relationships, and on
our knowledge oI basic Iacts. None oI these skills is speciIic to the development oI
computer programs; the knowledge we exploit is speciIic to the application domain in
which we are working. The remainder oI the book will show what and how much
computing can contribute to this most complicated step.
omain Knowledge: Formulating the body oI a program oIten requires knowledge about
the area, also known as domain, Irom which the problem is drawn. This Iorm oI
knowledge is called DOMAIN KNOWLEDGE. It may have to be drawn Irom simple
mathematics, such as arithmetic, Irom complex mathematics, such as diIIerential
equations, or Irom non-mathematical disciplines: music, biology, civil engineering, art,
and so on.
Because programmers cannot know all oI the application domains oI computing, they
must be prepared to understand the language oI a variety oI application areas so that they
can discuss problems with domain experts. The language is oIten that oI mathematics, but
in some cases, the programmers must invent a language, especially a data language Ior
the application area. For that reason, it is imperative that programmers have a solid
understanding oI the Iull possibilities oI computer languages.

4
Another advantage oI Scheme's notation is that we always know where to place an
operator or where to Iind it: to the immediate right oI the opening parenthesis. This is
important in computing because we need many more operators than just the Iew
numerical operators that we use in arithmetic and algebra.
5
It is common to speak oI the area oI a circle, but mathematically speaking, the circle is
only the disk's outer edge.
6
An arrow is keyed in as - Iollowed by .
7
This statement is true Ior any other programming language as well, Ior example,
spreadsheet languages, C, word processor macro. Scheme is simpler than most oI these
and easy to understand Ior computers. UnIortunately, to human beings who grow up on
inIix expressions such as 5 4, Scheme preIix expressions such as (+ 5 4) initially
appear to be complicated. A bit oI practice will quickly eliminate this misconception.
8
We will Iind out in section 8 why such errors are called 83ta errors.
9
As we will see later, the order is not completely Iixed. It is possible, and Ior a number oI
reasons, desirable to switch the order oI some steps in some cases.
10
An arrow is keyed in as - Iollowed by .
11
Others also call them FORMAL ARGUMENTS or INPUT VARIABLES.