CS70, Fall 2002

A Note About the Honor Code

In CS70, you will often be working with code supplied by the professor as part of the assignments. Only code provided by the professor, or written by yourself, may be used to complete assignments. Even if you think a particular bit of code is not central to the essence of the assignment, you may not use code written by anyone other than the professor or yourself.

If you have any questions about this policy, ASK FIRST. In the past, students have gotten into serious trouble because they assumed something was OK without asking first.

More information on the honor code can be found on the administrivia page.

Homework Assignment #1

The program for this assignment, and everything else except the README file, is due at 10 PM on Wednesday, September 11th, 2002. The README file is due at 1 AM on the following day (Thursday). Refer to the homework policies page for general homework guidelines.

This assignment has several purposes:

Overview

You have been hired by a small company that develops Web sites. Your first job will be to make modifications to a system developed by the firm's star programmer, who was recently killed in a tragic unicycling accident.

The system that the programmer developed is large and complex, but the programmer did a good job of dividing it up into small pieces. He even wrote special test programs that exercise the fundamental classes that the system uses. You have determined that you will need to modify one of those classes, which performs arithmetic on rational numbers.

Unfortunately, when you look at the code for the class and its test program you are dismayed, for it seems that the star programmer was far more concerned with whether the code worked than whether it was maintainable. In fact, it seems that he religiously followed the unmaintainability rules. After a few minutes, you go to your boss and tell her that it will be quicker to first spend time cleaning up the programming style, and only make the necessary modifications after the program has been made readable. Your boss agrees, and because the original code is so bad, she will even allow you to do a bit of renaming that will have effects elsewhere (see Tricky Stuff).

Your task for homework #1 is to clean up the style of the rational-number class and its associated test program. There are no known bugs in the program, so you can concentrate on simply cleaning it up without changing the output produced by the test program.

The program is composed of three files:

assign_01.cc
is the test routine that verifies the correct operation of the class,
rat.hh
is the "header file" that describes the interface to the rational-number class, and
rat.cc
is the implementation of the rational-number class.

In addition, there is a so-called Makefile, which makes it easy to compile the program on Turing by simply typing make at the command prompt. WARNING: the Makefile is very sensitive to how you download it. Do not simply select the text in your browser and the paste it into an editor window, or make will not work. Instead, follow the instructions below. If you download the file individually, you must name it "Makefile" or "makefile", using exactly that capitalization, or again make will not work.

The best way to acquire all of these files is to download all of them as a group. We have provided a tar archive for Unix/Linux users and a zip archive for use with DOS and Windows. First, create a new directory to hold your homework, and change into it. Right-click on the appropriate link in your Web browser and select "Save link as...". Save the tar or zip archive in your cs70/hw01 directory. After the file is saved, you can unpack it into that directory by typing "gzcat hw01files.tgz | tar xvf -" under Unix/Linux, or by running "unzip hw01files.zip" under DOS/Windows.

Alternatively, you could right-click on the link for each individual file and choose "Save link as..." to download it separately.

Your final submission should consist of five files:

Makefile
With one small exception, this can be the same as the file that was provided to you. The exception is that if you decide to change the names of the files that contain the rational-number class (rat.cc and rat.hh), you must make corresponding changes in the Makefile. It is up to you to decide whether to rename these files. If you do so, be sure to modify all places in the Makefile where they are mentioned.

Your Makefile must work correctly, and must produce an executable named assign_01. The graders will be using make to compile your program. If you have trouble getting make to work, first check to be sure that you downloaded the Makefile correctly. If that doesn't cure the problem, ask one of the graders or professors for help.

assign_01.cc
The C++ code for the the test program (commonly called a "test driver"). The name of this program must not be changed, no matter what you do to its internals.
rat.hh
The header file (interface definition) for the rational-number class. This file does not have to be named rat.hh. You are allowed to choose any name you like, so long as:
  1. The file has a .h or .hh suffix, and
  2. You remember to change the Makefile to match.
rat.cc
The code file (implementation) of the rational-number class. This file does not have to be named rat.cc. You are allowed to choose any name you like, so long as:
  1. The file has a .cc suffix (or another extension accepted by g++,
  2. You remember to change the Makefile to match, and
  3. You ensure that make still works with the name and suffix you choose.
README
A documentation file, as specified in the homework policies page. Note that this file is not due until 3 hours after the other files in the assignment.

You should create all of these files in a single directory that is dedicated to this assignment. You can create a directory using the mkdir command. I suggest that you have a "cs70" directory that will hold all assignments, and then a subdirectory for each individual assignment. For example, you might type the following commands:

    mkdir cs70
    cd cs70
    mkdir hw01
    cd hw01
    gzcat hw01files.tgz | tar xvf -
    emacs assign_01.cc

h When you are ready to submit your program, cd into the proper directory (e.g., cs70/hw01) and run the cs70submitall command. This command will prompt you for the assignment number (see the top of this Web page), and will then capture all of the source files, Makefiles, and README files in your directory, so BE CERTAIN that you don't have anything in your directory besides your assignment. Remember to submit early and often.

If you discover a mistake in your program, you can resubmit it using the same command. You can submit as many times as you like; only the last version will be used.

Since the README file is due later than the rest of the assignment, you must submit it separately (unless you have it done before the deadline). You can do this with the cs70submit command:

    cs70submit README
If you already submitted your code separately, DO NOT use cs70submitall to submit the README file, or it will appear that you missed the deadline even though you were really on time.

Details

The class defined by rat.hh and rat.cc implements a simple rational-number package. Rational numbers are represented as a pair of integers, the numerator and denominator. For convenience, the class ignores the fact that any real-life computer imposes a maximum value on integers.

The code you have been given is, to the best of our knowledge, correct and bug-free. However, it is written with very bad style. Your sole task is to improve the style, not to fix bugs. If you find any bugs, you should note them in the README file but should not fix them. (If you find no bugs, the README should mention that there are no known bugs.)

The requirement of no bug fixing is, perhaps surprisingly, very realistic. As a general rule, when you are correcting style in the real world, you should not fix bugs at the same time. If you follow this rule, it will be much easier to find out what happened after the fact, especially when you use a source-code control system (a subject you will study later, in CS121).

The revised class and test program must produce output identical to that from the original. You can check that the output is correct using the diff command. Before you start editing the program, do a test run and save the output, as follows (% represents your shell prompt, which will almost certainly be different on Turing):

    % make
    % ./assign_01 > original.out

The above commands will compile the program (make), run it (./assign_01), and save the output into a file named original.out (> original.out). You can use that file later to make sure the output hasn't changed.

How to attack the problem

There are a lot of things wrong with the program in this assignment. Here are some hints about what you might want to play with:

Compiling the program

As mentioned above, you can compile the program by simply typing make at the command prompt. One of the many advantages of using make is that it will run the compiler with switches that check for all sorts of simple errors. Your program must compile without any warning messages when the compiler is invoked with the -Wall -pedantic switches (as happens when you use make).

Running the program

If you are new to Unix, you may be wondering how you can test your program.

To run your program, simply type "./assign_01" (without the quotes). Since this program requires no input, you should immediately see the output on your terminal. If the program misbehaves badly, you can abort it by typing control-C.

You can look at the output of the original version by typing cat original.out. Alternatively, you can use the diff command to compare the output of the original with the output of the new version:

    % ./assign_01 | diff original.out -
If the two versions produce identical results, you will see no output on your screen. For example, if you changed "yup" to "yessss!", you would see something like:
    9c9
    < yup
    ---
    > yessss!

The README file

Every assignment in CS70 must be accompanied by a README file. The file must be named README in all uppercase letters. A detailed specification of the README file can be found on the homework policies page. For this assignment, make sure the README file contains:

Some Useful C++ Hints

For the most part, you should be able to complete this assignment without knowing anything special about C++. However, it will help to know a few things:

G++ Version 3

There are now two versions of the GNU C++ compiler (g++) on Turing: g++ and g++3. The latter is newer, slower, and less stable. However, it also produces better error messages, so it is worth learning to use it.

To use g++3, edit your Makefile and change the line that says:

	CXX	=	g++
so that it reads:
	CXX	=	g++3
Then type "make clean" and "make" to recompile your program.

Tricky Stuff

With every assignment, there are parts that can surprise you. Some of the "gotchas" in this assignment include:


Other Resources

There is more information on using C++ on Turing available in the departmental quick-reference guide and the C++ quick reference guide.


© 2002, Geoff Kuenning

This page is maintained by Geoff Kuenning.