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.
Clone the repository for this lab from the shared class directory:
If you try$ hg clone /cslab/class/csci235/labs/lab5
hg status, you should see nothing, because the
working copy and the repository match. If you try hg log,
you should see the (short) history of revisions that I made to the
repository before you cloned it.
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 108 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.
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
You should see that just the one$ hg status
.java file is modified.
Then do the actual commit with
Note that you do put the message inside quotes.$ hg commit -m "Filled in the heading comment"
We're now ready to begin the actual work. The basic plan is:
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:
@param tag and description for each parameter.
@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 adding code to 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.
Repeat the process in part 3 for hoursToMinutes
and minutesToSeconds.
Document them properly and test them individually so you know they are
right. For testing, you might wish to temporarily replace the prompt
and input (which you can do by commenting out part of what is there
and adding new test code).
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.
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.
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, displaying the distance in both units).
Don't forget to commit.
javadocOne 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 create the documentation files for your class 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.
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
before you end the script.$ hg log
Use handin to turn in your source file and the script file
as lab5. Do not turn in a printed copy.
You can find instructions for cloning (copying) the repository to your account at the end of the last lab or on the Mercurial tips page.
Keep in mind that the script file is not in your repository; so if you want it you will need to copy it separately.
* Note: this is clearly a fictional starship, of the sort appearing in most popular science-fiction stories. Neither special relativity nor general relativity applies. Unlike some of the best-known fictional starships, however, this one is not subject to temporal anomalies. (back)