CSCI 120: Lab 2

As we saw with algorithms, designing a program is very much a "top-down" process, proceeding from the general to the specific. But implementation (coding) is more "bottom up," proceeding from the simple to the complex.

The ideas are

to take small steps and
not to take the next step unless you're sure the last one was correct!

Objectives

The objective of this lab is to participate in the design and implementation of a Java program, in particular, to generalize an existing program. One motivating force here is that the end result is going to be a big chunk of Assignment 4! Take your time on this lab and don't rush things. Read the instructions and follow each step carefully. During the course of this lab, you will learn how to:

Decide what variables are needed
Decide what user input is required
Decide what output your program needs to provide
Decide what computation(s) your program needs to perform
Implement your program in small steps
Document your code with appropriate comments
Test your code to check its correctness and fix errors, if any

Problem Description

Write a Java program that takes as input the price of an item (or set of items) and the cash tendered by the customer, and outputs the cash to be returned, keeping the number of coins and bills to a minimum. For simplicity, we will assume that we only have single dollar bills available to give change. Executing the completed program will produce output similar to what is given below, where the numbers in italics are entered at the keyboard by the user. Notice that this program is similar (but not identical) to the ChangeMaker program that we discussed in class.

If you're stuck on any point in the design or implementation, please let me know!

Sample Execution

Below is a sample only. You might design your program differently, but in any case there should be (1) some introductory explanation, (2) prompts, (3) and output of the results of the computation. User input is in italics.

  This program will calculate your change, given the cost of your
  purchases and the amount of money tendered.  The number of dollar
  bills and the minimum number of coins will be returned in your change.

  Enter the total amount of your purchases:  5.32
  Enter the amount of cash tendered:  20.00

  The cash to be returned is $14.68, which can be given as
  14 dollars,
  2 quarters,
  1 dimes,
  1 nickels and
  3 pennies.

Getting Started

Don't begin coding right away. There are four stages to this lab: (1) Design, (2) Implementation, (3) Documentation, and (4) Testing. Below you will find instructions that will help you to design, implement and test a program which aims to solve the above problem. We begin with design, proceed with implementation and documentation, and finish with testing. In practice, documentation should be done in the design and implementation stages, but to clarify what documentation actually is, it is made into a separate stage.

Design

First we need to consider the problem statement and make some decisions about aspects of the program we will eventually implement. Let us bear in mind these two programming maxims:

Think before you code.
The sooner you start coding, the longer it will take.

Okay, okay... we're going to partly ignore the good sense of this wisdom of the ages. Start by looking at some code, namely the file ChangeMaker.java, which was discussed in lecture. We will build our program by extending this one. Hopefully, this much code will be thought-provoking, and you do want to pause to think before actually changing it. Write down on a piece of paper the answers to the following questions.

Beyond those in ChangeMaker.java, what additional variables (if any) will be needed in this program? What are their data types? Give each variable an appropriate name.
What user input is required? Note that ChangeMaker just reads in one int value; what will be different in your program? Write a sentence or two in English describing each input you expect the user to provide.
What output does the program provide? Ex. Introductory message, prompts, results. For each type of output you think of, write down what the program should print to the screen.
What computation(s) does your program need to perform? The answer to this question may affect the answer to questions 1 and 2 above if variables are needed to calculate and store the results of your computations. Update your lists of variables if necessary.

When you're done, show me your answers. I may have some comments or suggestions.

Implementation

Once we have a basic program design, we begin with the implementation. We write our program in small increments, compiling and testing along the way to make sure we are proceeding correctly. Follow the steps below carefully, making sure you are confident that the result of each step is correct before moving on to the next step.

Create a BlueJ project for this lab.
Download ChangeMaker.java. This file contains the definition for the class ChangeMaker. Use the "Edit/Add Class from File" menu of BlueJ to put it in the folder that you created in BlueJ for this lab.
Delete the line "centAmount = keyboard.nextInt();" we won't need it. Comment out everything else in the program after that line and ending with the last System.out.println(). That is put /* before the first statement mentioned and */ after the last. We need to concentrate on one part of the program at a time, and we will only restore what we have commented out when the appropriate new features of the program are working.
Use System.out.print and System.out.println statements, or modify the existing ones, to create your program's introductory output message.
At this point you have the beginning of a program that will run. Save, compile and run your program. Fix any syntax errors that appear. Make sure the output appears correctly as you expect.
Go back to the editor and add the variable declarations you decided on in your design. Note that many of the variables you need are already there, since we started with ChangeMaker. Just add the new ones. This will not yet affect the program's performance, because you are not yet using these variables.
Save, compile and run your program. This step simply ensures that you have declared your variables correctly. Fix any syntax errors that appear. The program's behavior should be the same now as it was after completion of step 5 above (make sure it is!).
Go back to your editor and add prompts for user input after the output of your introductory message. Use the keyboard object to read appropriate values from the user into variables that have been declared in your program. After getting the user's input, use System.out.println to echo the values that the user typed in back out to the screen.
Save, compile and run your program. Make sure that you are reading the user's input correctly.
Go back to your editor and remove the last output statements created in step 8 above, echoing the user's input back out to the screen. These are not needed in the final program output.
Add some of the calculations that your program needs to perform. There are a few new ones that you must introduce before you consider "uncommenting in" the computations in the original ChangeMaker.java. Do these one or two at a time, adding print statements for any intermediate results, so you can see them on the screen and ensure that they are correct.
Save, compile and run your program. Fix any syntax or semantic errors that occur.
Repeat the previous steps, removing extraneous output messages after ensuring correct results, until all of the calculations that your program needs to perform have been implemented and tested.
Complete the final output of your program so that it matches what's given in the sample execution section above.

Documentation

Although we have completed the implementation of our program (meaning the computer understands what to do), we are not completely done yet. Assuming you chose good variable names, it should be fairly easy for someone else to read your program and figure out what's going on. But to make this task easier, and to help you if you ever go back to look at this program in the future, we add comments into the code to make it more readable for humans. Follow the steps below to complete this lab assignment. (Note that there were some comments in the version handed out in lecture, but they were perhaps less than minimal, and they need changing here anyway.)

Add a comment header at the top of your program which includes:
- The name of your program (ChangeMaker.java) and a few words describing what the class does. E.g., "Change calculator"
- Your name
- Your login ID
- The course and section
- The date
- A brief description of the functionality of your program. Include here any assumptions your program makes. (E.g., the user is expected to input positive numbers in response to prompts, with a maximum of two decimal places.)
Add comments for your variables. If these are very brief, they should be placed at the end of the associated declaration line, and you should attempt to align them in the same column whenever possible. Otherwise, longer comments should be placed before the corresponding variable declaration. Comments should indicate what the variable is used for. Examples:
```
   double purchase;                   // amount of user's purchase
   int quarters;                      // number of quarters needed in change

   - or -

   // the following integers store the number of coins needed in change
   int quarters, dimes, nickels, pennies;
```

Add comments for program statements. It is not necessary, nor indeed desirable, to comment every line of code. For instance, the System.out.print instructions in this program are self-explanitory. But you need to make clear what's going on, especially for computations. Be sure to space and format your comments so that it is clear what the comment applies to. Examples:

   // get user's input
   System.out.print("Enter the total amount of your purchases: $");
   purchase = keyboard.nextDouble();
   ...
   change = tendered - purchase;    // calculate total change due
   ...
   // figure out number of quarters needed, and then calculate remainder
   quarters = centAmount / 25;
   centAmount = centAmount % 25;
   ...

Testing (and Debugging)

Although we have completed the implementation and documentation of our program, we need to conduct thorough testing to verify the correctness of our program and to fix any errors uncovered during the testing.

What is given in the sample output is just one test case. If your program can generate the same computation result as given in the sample case, it only means that your program can correctly handle the sample case. But your program may have problems handling other cases. It is the programmer's responsibility to design and execute test cases as well as fix bugs.

For the change making problem, check what your program does when cash payment is less than purchase price. Does your program generate meaningful output? Conceptually, what do you think you need to do to avoid this kind of problem? A peak at the first few pages of Chapter 5 will show you how to prevent such problems.

Now design and execute more test cases, check your results and fix any problems that you can fix with what we have covered so far.

Finishing Up

When you're finished, print the source code, hand it in, demonstrate the running of your program, and submit the BlueJ project electronically.