HW#4 Written Report
INTRO:
   The application coded for in the pair programming project is a
   graphic display which shows four roads on it with four cars that
   travel on them, one for each road. The roads are set up in a way so
   that two run vertically and two run horizontally, each intersecting
   with two other roads. The cars are different colors and sizes and
   each has its own traveling speed, which doubles when the car comes
   into contact with any intersection. The cars travel one at a time,
   the first one going west on the top horizontal road, the second
   going south on the right vertical road, the third going north on
   the left vertical road, and the fourth going east on the bottom
   horizontal road.

SYSTEM USE:
   My partner and I wrote our code using the Dr. Java environment
   which is used in lecture examples as well as in section
   reviews. Using the interactions window of this interface, a user
   would be able to create objects and call methods using the program
   we worked on, called "Car.java." The user can create a new object
   of type Car by using the constructor method. This method takes
   seven parameters in constructing the new object, the first being
   the director object to be queried by the car, the second being the
   road the car initially is traveling on, the third is the direction
   in which the car is traveling, the fourth is the width of the car’s
   rectangle representation, the fifth is the height of the rectangle,
   the sixth is the initial speed in pixels per frame of the car, and
   the seventh is the color of the car. For example, a user could
   create a new car object by typing "myCar = new Car(director, road,
   'W’, 20, 30, 4, Color.red)."

   The user can use two methods in the Car class to add and remove the
   Car object from an existing graphics window. To add the object, the
   user may call the "addTo" method. This method takes a parameter of
   whatever graphics window the user wishes to add the Car object
   to. For example, if a user types "myCar.addTo(gw)," the Car object
   will be represented in graphics window gw. To remove the Car from a
   window, the "removeFromWindow" method is used. This method takes no
   parameters and does not return anything to the caller, but removes
   the Car object from whatever window it is in. For example, a user
   types "myCar.removeFromWindow()" and the Car will be removed from
   its graphics window.

   In order to be able to move the car along its road, the user may
   use the car’s "advance" method. This method takes no parameters and
   does not return anything to the caller, but moves the Car object by
   a number of pixels equal to its "speed" value specified in the
   constructor. Depending on what the Car’s direction was initialized
   to, the Car will travel either north, south, east, or west at this
   speed. For example, a user may call the method on a car with speed
   4 and direction 'W’ by typing 'myCar.advance()' and that car will
   travel 4 pixels to the left.

   To check if a car is on any road in the program, the user may call
   the "carIsOnRoad" method. This method takes the parameter of
   whatever road the user wishes to check, and returns a Boolean value
   (either true or false) as to whether the car is on the road. An
   example would be if the user types "myCar.carIsOnRoad(firstAvenue)"
   and if the car is on the road named firstAvenue, the method will
   return true, if it is not on that road the method will return
   false.

   To see if a car is at an intersection with a road which it was not
   initially traveling on, the user may call the "getCrossRoad"
   method. This method takes no parameters, and returns the Road
   object that the Car is at an intersection with, or null if the Car
   is not at an intersection at that time. For example, the user types
   in "myCar.getCrossRoad()." If that car is in an intersection with
   firstAvenue, the method will return that. If the car is not at an
   intersection, the method returns null.

   The user can tell a Car object to speed up if it is in an
   intersection, but it may only speed up once per intersection. Using
   the "speedUpIfInNewIntersection" method, a user tells the car to
   double its speed value, but if this method is called more than once
   in a single intersection, it will only work the first time. This
   method takes no parameters and does not return anything to the
   caller. For example, if a user types in
   "myCar.speedUpIfInNewIntersection()," the Car will double its speed
   if it is in an intersection and that method has not been called in
   that intersection yet. If it is not in an intersection or if its
   speed has already been increased in the intersection it is in, the
   Car will remain at whatever speed it is traveling.
 
   A user may also query a Car object to find out what Road object it
   is traveling on using the "getCurrentRoad" method. This method
   takes no parameters and returns the Road object of whatever road
   the car is moving along. For example, if a user types in
   "myCar.getCurrentRoad()" and that road is traveling along the Road
   object firstAvenue, the method will return that firstAvenue Road
   object.

PROCESS:
   [My partner] and I worked on our project on Wednesday afternoon,
   Thursday morning/afternoon, Friday afternoon, Saturday
   morning/afternoon, and also on Monday morning/afternoon. We spent a
   total of around sixteen hours on this project as far as I can
   calculate working at least two hours on each of the days we met to
   work on the project. The project as far as the pairing was
   concerned went very well in my opinion, as [my partner] and I both
   were helped by each others presence at the computer while we were
   writing the code. Having two people instead of one working on a
   project is definitely a plus in my opinion, as each may have their
   own strengths that may help with the other’s weaknesses in any
   problem. Also, being able to switch off writing code helps a lot,
   relieving stress and making room for fresh ideas, especially when
   many hours are spent at the computer. Our approach to the program
   was basically to tackle the guidelines one-by-one without using
   dummy values for any of the methods we were writing, and at the end
   fine-tuning the code until it performed satisfactorily. The
   instructions for the project were very thorough and helpful and the
   comments already in place in the Car class were as well, so getting
   the idea of what each method was supposed to do was not hard at
   all, and writing code to do it just required us to use what we’ve
   used in class so far. Though not using dummy values was in a way
   difficult because we were not able to see how the project was
   developing while we wrote it, I believe it was less confusing since
   we did not have to write over our dummy values that may have become
   imprinted in our minds as being correct and we were able to keep
   thinking of ways to make the code do what we wanted without forcing
   it to produce artificial results. I do not remember us making any
   significant changes to the code based on what we had learned,
   besides maybe beginning to write a method and then realizing it
   called on another method in the code which we had already written,
   which simplified the work we had to do.

SYSTEM DESCRIPTION:
   For this project, we were required to implement the Car class using
   the design structure provided in the guidelines and by the JavaDoc
   comments that were already written within the class. From these
   comments and the instructions, we had to write basically everything
   else in the class, from the constructor to all the other methods
   inside it. Properties of the Car class are: The road on which it is
   traveling, the last intersecting road that it crossed, the
   direction of its travel, the Car’s speed, the avatar to represent
   it in the graphics window, the actual graphics window it is in, and
   the director to be queried for information. Responsibilities of the
   Car class are: To add and remove itself from a graphics window, to
   advance itself by its speed value, to check if it is on a certain
   road given the value of that road, too see if it is at an
   intersection with any road, to speed up if it is at a new
   intersection, and to provide the name of the Road object it is
   traveling on.

   The constructor is a very important part of this code, as it
   constructs new Car objects as they are asked for by a caller. In
   the constructor, six of the seven instance variables are
   initialized according to input parameters provided by the
   caller. Basically, all the properties of the Car are given values
   except for the graphics window it is displayed in, which is
   initialized soon after the constructor. Also, the car graphic is
   initialized so that it will center itself in a lane of travel
   depending on what direction it is required to go. For this, we used
   a "switch" method that changes depending on the value for the
   car’s direction. Depending on the direction of its travel, the Car
   will appear in the right lane at the beginning of the road that it
   is traveling on. An example of this switch taken from our written
   code:

      switch (direction) {
           case 'W':
               x = road.getX() + (road.getWidth() - width);
               y = road.getY() + ((road.getHeight()/2 - height)/2);
               body = new Rectangle(x, y, width, height, color, true);
               break;
           case 'S'
               x = road.getX() + (((road.getWidth()/2) - width)/2);
               y = road.getY();
               body = new Rectangle(x, y, width, height, color, true);
               break;
           case 'N':
               ...

   The first methods listed in the code are to add and remove the Car
   object from a graphics window. These methods are very simple and
   did not require much more than looking at the Road class’ similar
   methods but changing the prop added to be the Car object’s
   avatar. The next listed method is to advance the car by its
   speed. Since each car has a different speed and direction, we once
   again used a switch to define each car’s advancement by its speed
   dependent on which direction it was going. This method also calls
   on a Rectangle object’s moveBy() method to create the movement of
   each Car.

   The next method, carIsOnRoad(), tells whether a Car is on a
   specific Road by using a Boolean return value. Since this method is
   not dependent on the Car’s direction, a switch was not needed in
   this method, and it merely checks the coordinates of the car by
   using the Rectangle’s getX() and getY() methods against the
   coordinates of the road to check by using the Road class’ same
   methods along with the getHeight() and getWidth() methods of the
   Road class. Although this method seems to be complex at first
   glance, it needs only to be thought of in a geometric sense,
   perhaps with a drawing for visual aid like we drew to be able to
   write it, to understand it.

   The getCrossRoad() method that is in place next tells the caller
   the name of the Road object that the Car is at an intersection
   with. For this, we query the Director object to provide values of
   Roads to check as well as use an if-clause embedded in a
   while-clause to achieve the desired results. The while-clause
   enables the road-checking to stop once there are no roads left to
   check (i.e. when the director is queried to provide a road and
   returns a null value). The if-clause enables us to eliminate the
   road that the Car is traveling on as an intersection, since it will
   always be traveling on that road, as well as skip to the next road
   provided if the Car is not at an intersection with the previous
   one.

   The method speedUpIfNewIntersection() queries the getCrossRoad()
   method and uses the instance variable for the last road intersected
   to speed up the Car to twice its speed value if it is inside an
   intersection where it has not been before. This method uses an
   if-clause embedded inside another if-clause. The first is to check
   if the car is actually at an intersection.  The second checks if
   its intersection is a new one, and if it is, doubles the Car’s
   speed. If the intersection is not new, the Car remains at its own
   speed. This method in its entirety is displayed here, to provide an
   example of the embedded if-clause that is present here as well as
   in getCrossRoad():

      public void speedUpIfInNewIntersection() {
         if (this.getCrossRoad() != null) {
            if (roadLastIntersected != this.getCrossRoad()) {
               speed = 2 * speed;
               roadLastIntersected = this.getCrossRoad();
            }
         }
      }

   The last method in this class is getCurrentRoad(), which simply
   returns the Road value stored in the instance variable for the road
   that the Car is currently traveling on. This was probably the
   easiest and simplest method to write since it has only one
   statement in it.

TESTING AND EVALUATION:
   As I mentioned before, we wrote our project in its entirety before
   testing it out at all and did not use any dummy values, and this
   enabled us to find out exactly where things were going wrong with
   our code when we finally did compile and run it for the first
   time. Overall, we mostly did some minor troubleshooting on it
   during the compilation phase, fixing errors as needed when the
   compiler returned them. This was not very difficult as they were
   mainly just syntax errors and nothing major was wrong with the code
   because the instructions and comment guidelines were very
   straightforward. As for running the code, there was one major
   problem we had with the graphical display, and that was the cars on
   the two horizontal roads were traveling in strange ways. The top
   car traveling west seemed to be on the screen for only a moment as
   it was at a very high speed, and the bottom car traveling east
   never accelerated at any intersection. We worked on this problem
   for much of the time we spent on our project, asking the CSE
   consultants about it many times but didn’t really find an answer
   until Monday afternoon a few hours before it was due. We had
   narrowed the problem down to the carIsOnRoad() method as we could
   find no problems with anything else in the hours of troubleshooting
   we had done. After deleting the line "roadToCheck = road" from the
   beginning of the method, everything worked out fine. We immediately
   understood what was wrong in that we had written over the
   initialized value for "roadToCheck" and were very relieved that our
   program finally worked properly. After that point, everything
   seemed to be fine, clearly written, and follow the instructions
   satisfactorily.

CONCLUSION:
   A main point that was brought to us through our troubleshooting is
   that major problems can be caused by minute coding mistakes, ones
   that are very hard to notice unless the code is gone over
   line-by-line for hours at a time. Other than that one problem, I
   thought that this project was very satisfying and we got a very
   good feeling after completing it together. The pairing idea was
   very good and lets people in the class meet and work with people
   they otherwise might not have, and is certainly helpful in a larger
   assignment such as this was. Overall, this project greatly
   increased my fluidity in writing in Java and heightened my
   understanding of all the concepts we have been going over in class.