Lab 6
Revision

Out October 11, due by midnight, Friday, October 14

Introduction

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.


Contents


Understanding the code

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.

Don't panic

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.

Javadoc

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.

Revision

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.

Gravy

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.

What to turn in

Your completed assignment should incldue: