7.2 The Specification

For this chapter we are going to assume that you have been given the assignment to "write a program that acts like a four-function calculator." Typically, the specification you are given is vague and incomplete. It is up to you to refine it into something that exactly defines the program you are going to produce.

The first step is to write a document called The Preliminary Users' Specification, which describes what your program is going to do and how to use it. This document does not describe the internal structure of the program or the algorithm you plan to use. Following is a sample specification for the four-function calculator:

Calc

A four-function calculator

Preliminary Users' Specification

Dec. 10, 2002 Steve Oualline

Warning: This is a preliminary specification. Any resemblance to any software living or dead is purely coincidental.

Calc is a program that allows the user to turn his $10,000 computer into a $1.98 four-function calculator. The program adds, subtracts, multiplies, and divides simple integers.

When the program is run, it zeros the result register and displays its contents. The user can then type in an operator and number. The result is updated and displayed. The following operators are valid:

Operator	Meaning
+	Addition
-	Subtraction
*	Multiplication
/	Division

Example (user input is in boldface):

calc 
Result: 0 
Enter operator and number: + 123
Result: 123 
Enter operator and number: - 23
Result: 100 
Enter operator and number: / 25
Result: 4 
Enter operator and number: * 4
Result: 16 

The preliminary specification serves two purposes. First, you should give it to your boss (or customer) to ensure agreement between what he thought he said and what you thought he said. Second, you can circulate it among your colleagues to see whether they have any suggestions or corrections.

This preliminary specification was circulated and received two comments: "How are you going to get out of the program?" and "What happens when you try to divide by 0?"

So a new operator is added to the Preliminary Users' Specification:

q -- quit

We also add another paragraph:

Dividing by 0 results in an error message and the result register is left unchanged.

IV + III = VII A college instructor once gave his students an assignment to "write a four-function calculator." One of his students noticed that this was a pretty loose specification and decided to have a little fun. The professor didn't say what sort of numbers had to be used, so the student created a program that worked only with Roman numerals (IV + III = VII). The program came with a complete user manual—written in Latin.