Lab 4: Writing simple methods

The primary goal of this lab is to get practice with basic methods. The logic is very simple in this lab; the point is to become familiar with the syntax of methods and how to document them.

This lab also gives you an opportunity for more practice with Mercurial.

0. Background

A revision control system provides a way that you can track groups of changes made to a set of files. Being able to manage the changes is especially important when more than one person is working on a project. But even when working by yourself, it can be helpful to be able to back up to a previous revision.

The revision control system that we will be using is Mercurial. In this lab, you'll begin to learn how you can use it for projects and labs in this course.

Key concepts

With any revision control system, you will have a distinction between the working copy of a program and a repository that stores its history. You can check out a particular revision from the repository to create a working copy, and you eventually commit the changes you have made back to the repository. Mercurial hides a copy of a repository inside your working directory. You'll usually start work in one of two ways: either you will initialize a new repository where you are working, or you will clone a repository that someone has already set up. The Linux command for Mercurial is hg. There is some help built in: you can find out what Mercurial commands exist with hg help, and you can find out about a specific command, such as add, with hg help add. The commands that you are most likely to be interested in are:

• hg init
• hg clone repository
• hg add filename
• hg revert filename
• hg commit -m "log message"
• hg log
• hg status

1. Setup

Clone the repository for this lab from the shared class directory:

hg clone /cslab/class/csci235/labs/lab4

2. Specification

You are the programmer on an interstellar space ship, traveling at light speed. Your captain wants to know how far the ship is from our home planet; all you know is how many days you have been been traveling. You are to write a program that asks the user for a number of travel days and displays the distance from the home planet in kilometers.

The speed of light is 2.997925 x 10⁸ meters per second. To take a number of days and compute a number of kilometers using a meters per second rate takes several conversions. We will compute each step using a separate method.

3. First step

Open your source file in Emacs.

emacs StarshipDistance.java &

Note that it has a main method, and also some method stubs that are commented out. Before you do anything else, fill in the heading comment appropriately. Save your file, and make sure that it still compiles cleanly. To commit your changes to the repository, first check the status with

hg status

hg commit -m "Filled in the heading comment"

We're now ready to begin the actual work. The basic plan is:

• Convert from days to seconds.
• Using the number of seconds and the velocity, compute the distance travelled in meters.
• Convert from meters to kilometers.

First implement the conversion from days to hours. Find the method stub that has the signature

 daysToHours(int)

Move the start-of-comment marker down so that the method is no longer commented out. Then fill in the body so it works.

After you have written it, you must do two things: document and test. To document, remember the rules for documenting methods. Write a block comment (start with two stars, and with stars all along the left side) containing:

• A one-sentence description of the functionality of the method in the imperative.
• Except for trivial methods, a few sentences describing the algorithm.
• A @param tag and description for each parameter.
• A @return tag with a description of what's returned.

These methods can count as "trivial," so you can skip the second part (the description of the algorithm).

So the comment for daysToHours() would look something like:

    /**
     * Convert days to hours.
     * @param days The number of days.
     * @return The corresponding number of hours.
     */

Test your method by changing the main method so that it only calls your method and prints the result. Try a few examples, and make sure it is working. When you are satisfied, commit it to your repository.

4. More conversion methods

Repeat the process in part 3 for hoursToMinutes and minutesToSeconds. Document them properly and test them individually so you know they are right.

Then do the same for daysToSeconds, but instead of calculating the conversion directly, have this method call the other conversion methods to get its result. Document and test. Now you know that entire sequence of methods is right.

You can commit at any point that you feel that the program is consistent. If you haven't committed since completing daysToSeconds, do so now.

5. The heart of the matter

Now go ahead and fill in the code for secondsToMeters, calculating distance by time times velocity. You can write big number literals using "e" (for "exponent") to mean "times 10 to the..." That is, you might make a variable like this:

double speedOfLight = 2.997925e8

Document and test. Then repeat the process for one more conversion method, metersToKilometers.

Finally, you can use calls to daysToSeconds, secondsToMeters, and metersToKilometers to write daysToKilometers. Since you've tested all the components, you should have nothing to worry about for the correctness of this method.

To wrap up, make sure everything is documented well (including the block at the beginning of the program and including all local variable declarations). Also make sure the main method has been cleared out of testing code, and works now according to the specification.

This would be a good time to commit, again.

6. One more conversion

This is an American vessel, and your captain doesn't know what a "kilometer" is. Write and use an extra conversion method, from kilometers to miles, so that the more familiar unit of measure is used (and use it in your main method).

Don't forget to commit.

7. Invoking javadoc

One of the reasons for documenting our methods in exactly the form specified is that it makes it possible for additional tools to produce neatly formatted documentation. You can see what the documentation for your classes by running the command

javadoc StarshipDistance.java

If you use ls now, you'll see that javadoc has produced a bunch of new files. To see you documentation, use your browser's 'open file' feature to open the file StarshipDistance.html from the directory where you are working.

8. Turn in

Remove your .class file(s). Then create a script file as before (compile and run). Run the program using 1 day, 5 days, 16 days, and 80 days. After you have run the program, include

hg log

Print your source file and the script; hand them in as hard copy.

Use handin to turn in your source file and the script file as lab4.

8. Cloning a repository to your account

You can copy the repository (with all of its history) to your account as a Mercurial clone. Assuming that your account name is mortimer.snerd and that you already have a subdirectory named csci235, you'd do the command

hg clone . ssh://mortimer.snerd@cslab25/csci235/lab4/

The script file is not in your repository. If it is named typescript you can copy it with the command

scp typescript mortimer.snerd@cslab25:csci235/lab4/