Out October 11, due by midnight, Friday, October 14
This assignment emphasizes the following topics:
You should read through the entire assignment before beginning any of it.
As usual, you are encouraged to collaborate on this assignment. In particular, you should find at least one other person to help check your documentation for comprehensibility, clarity, and style. You may also find it a lot easier to figure out what the mystery code is doing if you work on it in pairs. Of course, your final work should be your own, and you must acknowledge the contributions of your peers. Please include the names of anyone with whom you collaborate in any way on this assignment, and indicate the nature of the collaboration. Please make sure for this assignment that you have collaborated with at least one other person.
The assignment is due by midnight on Friday, October 14, to sd-psets@lists.olin.edu, or as hardcopy to Katie.
For this assignment, we are providing a code file:
MysteryBall.java as part of a revised
BallWorld project.
We highly recommend that you download the entire BallWorld project. This will enable you to run the code to see what it does. [The new BallWorld project also contains the subclassed Balls we built in class on September 22.]
MysteryBall implements the Ball interface, suitable for use in BallWorld. Remember BallWorld? The file is far from properly documented, and its style leaves a lot to be desired.
Your job for this assignment is to clean up the code. Specifically, you should improve MysteryBall so that it is significantly more readable. You shouldn't change the behavior of the code, but you should fix its style, and add comments and documentation.
Yes, the code looks rather scary, and the act method looks like a nightmare of repetitive nonsense. Don't panic! Take things a little bit at a time, work with someone else, and you'll be able to understand it.
The first step is to run the code and see what it does. Knowing what the code actually does will give you a framework for understanding what each part of the code is for. Download the project, open it in NetBeans, and run it. You should see a button for lab6.MysteryBall. Go ahead and click it. Click it again. Oooooh. But wait, there's more! Click on one of the balls, and then hit the space bar a few times. Now drag one of the balls in the mess 'o balls you just made. Wheeee. Come back when you're ready to continue.
Describe (very briefly) the properties of MysteryBall that you've just seen. Think about (you don't have to write this part down) what you would have done to achieve this behavior.
The second step is to glance over the code to see if there are any
surprises. DoubleVector seems kind of odd. It's actually
another class in the lab6 package, and is just a pair of
public doubles called x and y.
You'll notice that there are two fields that point to other
MysteryBalls. Their secret is hidden in the userTyped
method and the one-arg constructor.
Imagine that you have a single MysteryBall,
created with the no-arg constructor, and that you've typed the space
bar at it. Figure out what the userTyped method does
by drawing out the box, tag, and dial diagrams. Don't forget to
include a tag and box for the DoubleVector. Draw the
results of hitting the space bar at least two times, and indicate in
your diagram the original MysteryBall and in what order the other
two MysteryBalls were created.
Now tackle the act() method. You should have seen
two distinct behaviors when you were playing with the application.
Figure out which part of the act method handles each.
Add some inline // comments to indicate the behaviors.
You may want to refer to your diagram to figure out what the rest
of the act method does.
What is the anchor field for? How is
it set up? How is it used? Make sure you indicate it appropriately
in your drawing.
One requirement for your improved file is proper Javadoc comments. A Javadoc comment might look something like this:
/**
* Gets the next number in the series.
* @param cur the current number
* @return the next number in the series
* @throws IllegalArgumentException if the argument isn't an element of
* the series.
*/
public int getNextNumber(int cur) throws IllegalArgumentException {
Javadoc comments begin with /** and end with */.
The first sentence should start with a present tense verb, as if there were an
invisible "This method ..." before it. There can be more than one sentence in
the description, but the first sentence should describe the purpose of the
method as completely as possible while being concise.
A Javadoc comment should describe what the method does or what it is for. It should never describe how the method works. Use inline comments in the body of the method for that.
After the description, the arguments to the method should be described, in
the order that they appear in the method signature. The @param
tag is followed by the name of the argument and then its description.
If the method has a return type that isn't void, you
should have a line that begins @return and describes
exactly what the method returns. Be sure to indicate any unusual return
values for special cases.
If the method throws any exceptions, you should include a @throws
line that indicates the type of exception thrown and the circumstances under
which the exception is thrown.
Now that you understand the code and you've documented it, it's time
to fix it up. None of the fields have been marked private,
some of the variable names may be a bit wacky for your taste, and that
act method is just too long and repetitive. See if you
can clean up the act method by pulling common code into
separate methods.
Hint: the DoubleVector class might come in handy
for some of your new methods.
If you create new methods, make sure they are properly Javadoc'd!
Remember, the purpose here is to clean up existing code. You should not change the functionality or behavior of the MysteryBall.
There are a few bare numbers in the code. Some of
them are relatively arbitrary, but related to one another. You should
give them meaningful names and turn them into constants. Remember that
a constant is a public static final field.
This is the target of this lab: you should have a picture of the
MysteryBall instances, fully Javadoc'd code, and a cleaned up
act method, with at least one extra method factored out
to make act easier to read.
The DoubleVector is kind of anemic. There are things
you can do with vectors, like adding and normalizing, that would make
your MysteryBall code even cleaner. See if you can add the appropriate
methods to DoubleVector. Don't forget to Javadoc them!
If you're really adventurous... how would you delete a MysteryBall so that one chain gets divided into two? Make sure to handle the ends properly.
Your completed assignment should incldue: