5 Important Software Engineering Practices / Concepts

It's been a good semester of Software Engineering so far and I have learned a lot.  Of course there are too many important tidbits too share in one post, but here I will share 5 points that stuck out to me which will you will hopefully find interesting or useful (plus it will help me review for the upcoming midterm!).

---

1. Why should you always override the hashCode method when you override that object's equals method?
   
   The contract of the hashCode method states that if two objects are equal according to that object's equals method, then calling the hashCode method on the two objects must return the same integer. Since modifying the equals method of the object can change the definition of what makes two object equal, the hashCode method must also be overridden to stay consistent with the new definition.


2. What are the four properties that any implementation of the equals function should exhibit when comparing two non-null objects?
   
   
   1. Reflexivity: x.equals(x) must return true.
   2. Symmetry: x.equals(y) must return the same value as y.equals(x).
   3. Transitivity: If x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) must also return true.
   4. Consistency: x.equals(y) must return the same value over multiple calls to equals given that no information used in the comparison is changed.


3. Which property of the property Ant tag should you use to make properties representing paths? Why?
   
   While the value can work, you should use the location property of the property tag because the location property will change the file separators (i.e. '/' or '\') to the one that the operating system uses while the value property will not. Hence, using the location tag allows for better portability as it will change the separators in the paths to match the operating system invoking Ant.
   


4. What is the syntax do you use to access the value of a property defined in an Ant build file? For example, how would you access the value of:
   <property name="new.property" value="new />
   
   Surround the property name with ${ }. So ${new.property} may be used to access the value of the sample property above.


5. What are the three general categories of test cases?
   
   
   1. Acceptance tests: The program achieves and passes some basic requirement. For example, a Robocode robot always wins against a certain sample robot.
   2. Behavioral tests: The implementation actually works as intended. For instance, the Robocode robot actually follows the strategy by moving to the specified locations through out the battle.
   3. Unit tests: Test small self-contained classes or methods in isolation. For example, testing the output of a Robocode robot's fire-control method to ensure that the output matches the expected values without actually running the battles to check the robot's behavior.
      

---

And there you have 5 of the software engineering highlights that I have seen so far. Hopefully you have picked up something new and useful and I hope to share more with you as I continue my journey through the wonderful realm of software engineering!

Group Projects Made Easy - Subversion and Google Project Hosting

Introduction
In software engineering, there are many problems that are just too large for a single developer to tackle in any timely fashion and require multiple software developers to work in tandem. However, this can lead to many problems. For example, how does one ensure that they are working on the latest version of the project or that one's changes are not overwritten by another developer's modifications? These problems are magnified as more and more developers are added to the project, yet large projects with many programmers are common and run successfully without these problems. So how do they do this? The answer is that they use configuration management tools like Subversion. Here I shall share my initial experiences in using the Subversion configuration management tool and the Google Project Hosting website to host my CrazyTracker robot.

---

Subversion and Google Project Hosting
So we want to collaborate with others on this CrazyTracker robot, but how do we do it? First off, we need to get the tools required for Subversion. There are two main components of Subversion: a client program to communicate with the source code repository and a server to host said repository. I use a Windows operating system so I chose to use the TortoiseSVN client which allows the user to right click a folder and choose various commands from the pop up window. As for the server, we can easily create one by making a new project in Google Project Hosting. Once those are set up, it is just a simple matter of checking out the empty source directory of our new project, adding the CrazyTracker project's files in TortoiseSVN, and committing the changes to upload the the project to the Google Project Hosting server.

Now that the code is up there, we have to add some documentation in the form of wiki pages (i.e. user / developer guides) and add some "committers" to work on the project. Once that is completed, anyone can see the source code and anyone with committer permissions can upload their changes to the repository using Subversion.

Some of the commands available through the TortoiseSVN user interface.
Includes the "Blame" command which shows the last person that modified each line.

---

Conclusion
Overall, setting up the robocode-fch-crazytracker project on Google Project Hosting was relatively quick, easy, and painless. TortoiseSVN installed with no problems on my Windows computer and Google's simple and intuitive interface made creating the project and its documentation quite painless. If anything, the only gripes I had about the whole process was the fact that I had to check out the empty project to upload the original source files (why can't we add source files when creating the project?) and that the wiki markup language assumes that words with capital letters are links to other wiki pages and puts a "?" link after them. As a result, I had to put a "!" before those words to make those links go away which was a simple fix, but it did get annoying after a while. However, my first experience with Subversion and Google Project Hosting was definitely a good one and I can see how such tools can help with collaboration. Subversion in particular has some very interesting features (for instance, it can tell you who changed which lines of code with the blame function!) and I am definitely looking forward to using these tools for my future group projects. Now that you have seen just how easy it is to set up the tools needed to make group work that much less painful, let's get collaborating!

CrazyTracker

Introduction
If you have been keeping track of this blog, you might remember the post on Robocode katas.  While those exercises may have been a little mundane, they were my first step on the road to the ICS 314 Robocode Tournament for which I had to create my own robot to compete along with the various test cases needed to ensure that it works as intended.  Consequently, I have created a slightly more complex robot called "CrazyTracker" to compete in the tournament (and hopefully win!).

---

Overview
Robocode robots have three main functions: movement, firing, and targeting.  CrazyTracker incorporates all of these in different ways.

Movement:
CrazyTracker uses a random movement pattern (hence the crazy) where it moves to a random point between 50 and 150 pixels away every iteration of the run loop.  The idea is to prevent it from being predictable so it can dodge as many of the opponents bullets as possible.  In addition, it will move in a random direction away from a wall or rammed robot for a random distance between 50 and 100 pixels.  This is to prevent it from getting hung up on walls or enemies and to keep those enemies at a distance to reduce the amount of damage taken.

Using random movement to dodge enemy bullets.

Firing:
CrazyTracker uses two factors in it's firing algorithm as it uses both the current hit rate (how many bullets have hit so far / total number of bullets fired) and distance to determine the strength of the bullet to fire, if it should fire at all.  Here, the robot tries to reduce the energy wasted on missed bullets as it fires weaker, but cheaper bullets at longer distances and only fires at closer distances if the hit rate is too low.

Tracking:
CrazyTracker uses a simple targeting scheme.  The targeting algorithm basically just scans for the enemy, points the gun at it, and shoots.  While I did want to add some leading if the enemy robot is moving, the current algorithm only aims for the center of the enemy.  While this means that it is not as accurate as it could be, it still allows CrazyTracker to fire at enemies regardless of which way its body is facing which varies a lot due to the random nature of its movement.

The targeting algorithm faces the gun towards the enemy when it is time to fire.

---

Results
While I believe that my strategy is sound, it did not turn out so well in practice.  CrazyTracker can only reliably beat the SittingDuck, Crazy, and Fire robots and even then, it does lose to Crazy and Fire every once in a while due to its random nature.  The results versus the other sample robots are even worse with a 48% win rate against Tracker, 41% against Corners, 19% against RamFire, 18% against Spinbot, and an abysmal 15% against Walls.  This is probably due to the targeting algorithm as it fires at the center of the enemy, hence it has a hard time hitting fast moving or non-linearly moving targets like Walls or Spinbot.  Here some leading could have helped.  The low win rate against RamFire is likely due to the random nature as to how CrazyTracker handles running into another robot.  This means that it can get stuck in a corner or just spin in circles if it is unlucky, hence giving RamFire the advantage.  That behavior could be fixed, but I wanted to keep that random aspect even though it could create a disadvantage.

---

Testing
To check the the functionality of the CrazyTracker robot, I have created 6  JUnit test cases.  Two of these test cases are acceptance test cases which just check to see that CrazyTracker is in first place against a certain robot (Crazy and Fire in my case) and can beat that robot at least 80% of the time to account for its random nature.

In addition to these acceptance tests, I also have two unit tests.  The first unit test checks the a subclass of Robot that I implemented that provides a moveToPoint method and ensures that the moveToPoint method actually moves the robot to that point and that it properly handles points that are out of reach (i.e. outside of the battlefield) by trying to move to the closest valid point.  The second unit test checks CrazyTracker's calculatePower method.  This method determines the power of the bullet that the robot should fire (if any) depending on the its current hit rate and the distance from the target and the unit test ensures that it returns the expected values at the boundary cases.

Finally, I created two behavioral tests to check the firing and tracking behaviors of the robot.  For firing, I wanted to make sure that only the bullets of the powers specified by the calculatePower method were being fired, so it checks all of the bullets and sets a flag variable to true if a bullet with an unexpected power is found.  The tracking test pits CrazyTracker against the SittingDuck robot and checks that CrazyTracker's power never drops below 95.  This would be the case if the tracking algorithm works properly as each successful hit would restore energy, hence the making the robot gain energy if the bullets hit as they should.  The power threshold of 95 must be  used however as the initial bullet shot will drop the energy below 100 until it hits.

All in all, I believe these test cases cover the majority of CrazyTracker's features and functions and help ensure that everything is working as intended.

---

Conclusion
Overall, CrazyTracker was not only a good experience in learning Robocode, but also a great way to learn software engineering techniques like the use of automated quality assurance tools. As mentioned, CrazyTracker made me learn how to use testing tools like JUnit to help ensure that everything works and it has also showed the usefulness of other tools like Checkstyle, PMD, and Findbugs.  These tools do not do much in terms of testing, but they help to verify that my code is properly formatted and that there are no obvious bugs.  Finally, this project has taught me that adamantly sticking to a plan is not always the best idea.  From beginning to end, I kept the same general strategy behind the CrazyTracker robot even though it became obvious that it would be hard to beat many of the sample robots with that design.  Nevertheless, I stuck with that strategy until it was too late to make any real changes.  As a result, I learned that I should be more flexible as that could lead to more optimal solutions.  However, I do hope that CrazyTracker will be able to hold its own against the other robots in the tournament despite its weakness and hopefully the random number generator will return values that are in my favor.    Go CrazyTracker!

Building Systems with Ant

Introduction

Ever wish there was an easier way to build your Java projects?  Tired of using the command line to manually run all of your fancy tools?  Well wait no longer as Ant can automate your build processes with the help of a few user-defined XML files.  These XML files are created using a special subset of the XML language and to learn this we shall once again use the concept of code katas.

---

Tasks

1. Ant Hello World - Print Hello World.  Learn the <echo> element
2. Ant Immutable Properties - Show that Ant properties are immutable once they are set.  Learn the <property> element.
3. Ant Dependencies - Learn how the depends attribute of the <target> tag works.
4. Hello Ant Compilation - Use the <javac> element to compile a Java program.
5. Hello Ant Execution - Use the <java> element to run a Java program.
6. Hello Ant Documentation - Use the <javadoc> element to generate the documentation for a Java program.
7. Cleaning Hello Ant - Create a target that deletes the build directory to clean the system.
8. Packaging Hello Ant - Clean the system and pack it into a zip for distribution.

---

Experiences

Most of the katas were simple and easy to complete using a few targets and lines of code.  The only kata that gave me problems was the Packaging Hello Ant kata.  While it was simple to package all of the contents of the working directory into a zip archive, it was slightly more tricky to pack all of those contents within a folder inside of the zip archive.  To do this, I had to use the <copy> element to copy the contents of the working directory to a new temporary directory.  Then I could specify that I wanted the new directory and all its contents to be included by the <zip> element to create a zip archive with the desired structure and delete that temporary folder.  Hence, this exercise took a little more thinking as to how I would get the appropriate structure for the zip archive.

From these exercises, I learned how convenient build systems can be.  With a single command, I could compile a program, run it, generate documentation for it, clean the project, and pack it for distribution.  This would take many command-line operations and being able to do it just by typing "ant -f dist.build.xml" saves a lot of effort and time.

Overall, these exercises have given me a better appreciation for build systems, especially Ant.  Not only are they extremely convenient, they are also quite simple to use as the basic XML language used to direct Ant is rather simple and well documented.  Consequently, I am definitely looking forward to seeing Ant's true power as I start to work on bigger and bigger systems and see just how much simpler it makes the building process.

Code Katas and Robocode

How does one become great at something?   Of course, there are many possible factors, but the bulk of one's progress towards greatness comes from practice.  From learning a musical instrument to martial arts, practice is a key component to becoming better at whatever task is at hand.   Programming is no different, but developers tend to do most of their practicing on the job  leading to mistakes and difficulties as they work on real projects. To combat this, developers can use what are called code katas. These are short, open-ended programming problems to be solved outside of a project environment and are designed to serve as practice sessions for software developers.  There are many different katas for many different systems and languages, but here we shall focus on a set of 13 katas for the Robocode system in the Java programming language (Learn more about code katas!).  Now what is Robocode you may be thinking?  Robocode is an open source software system that allows users to build software tanks that can move, find enemies using its radar, and fight using its gun and these katas help to introduce new users, such as myself, to the basics needed to create an unbeatable fighting machine.  (Learn more about and download Robocode)

---

The Katas

• Position01: The minimal robot. Does absolutely nothing at all. 
• Position02: Move forward a total of 100 pixels per turn. When you hit a wall, reverse direction.
• Position03: Each turn, move forward a total of N pixels per turn, then turn right. N is initialized to 15, and increases by 15 per turn.
• Position04: Move to the center of the playing field, spin around in a circle, and stop.
• Position05: Move to the upper right corner. Then move to the lower left corner. Then move to the upper left corner. Then move to the lower right corner.
• Position06: Move to the center, then move in a circle with a radius of approximately 100 pixels, ending up where you started.
• Follow01: Pick one enemy and follow them.
• Follow02: Pick one enemy and follow them, but stop if your robot gets within 50 pixels of them.
• Follow03: Each turn, Find the closest enemy, and move in the opposite direction by 100 pixels, then stop.
• Boom01: Sit still. Rotate gun. When it is pointing at an enemy, fire.
• Boom02: Sit still. Pick one enemy. Only fire your gun when it is pointing at the chosen enemy.
• Boom03: Sit still. Rotate gun. When it is pointing at an enemy, use bullet power proportional to the distance of the enemy from you. The farther away the enemy, the less power your bullet should use (since far targets increase the odds that the bullet will miss). 
• Boom04: Sit still. Pick one enemy and attempt to track it with your gun. In other words, try to have your gun always pointing at that enemy. Don't fire (you don't want to kill it). 

---

Completing the Katas


While working on the katas, it became apparent that the difficulty level between exercises varied quite a bit.  Position01 and Position03 were quite straight forward as only simple calls to the Robocode library functions were needed and others like Position02, Boom01 to Boom03, and the Follow katas added the use simple event handling concepts.  These were quickly completed after a few looks at the Robocode API documentation and served as a stepping stone for the harder katas.

However, Boom04 was slightly more complicated as the gun and the robot could have different headings, hence the heading that the gun needed to point to had to be calculated.  The only way to find the position of an enemy is to use the getBearing() method which returns the angle of the enemy relative to the robot's current heading.  Hence, I had to calculate what heading that bearing corresponded to so that I could rotate the gun to the enemy's position.  I also decided to add some checks to ensure that the gun took the shortest path possible to the enemy's position as any turns greater than 180 degrees would be changed to a turn in the opposite direction.




Furthermore, Position04 and Position05 introduced more complications.  These two katas ask for a robot that can move to a point and the library does not provide any functions like that.  Consequently, I had to create my own moveToPoint functions.  These function use trigonometry (http://www.clarku.edu/~djoyce/trig/ was a big help!) to determine the heading and distance to the point, turn the robot to that heading, and moves the determined distance.  Initially, these functions had a bug where the robot would get on top of the point, but slowly move even though it should have detected that it was on the point and stopped.  This problem took a while to debug and it was due to the fact that the Robocode system uses double floating point values for the coordinates of the battlefield which made finding exact positions a little tricky.  For example, if I told to robot to go to (400, 600) and the Robocode system had the robot's position at (400.0000000000001, 600.0) it would constantly try to adjust and never stop as the coordinates are not equal.  As a result, I decided to round the coordinates to integer values of the long data-type to prevent such precision errors as the fraction-of-a-pixel differences are unnoticeable.  Position05 also introduced another problem in that a robot cannot actually reach the corners of the battlefield due to its body dimensions and would push against the wall ad infinitum.  Therefore, I had to modify the moveToPoint functions to adjust points that are outside of the reachable range.  Since these functions are shared by the last three Position katas, I decided to put them in a separate subclass of the Robot class to prevent a lot of copy and pasting (You may find the source code for this subclass here).

Finally, there is Position06.  This kata built on the problems from Position04 and Position05 with the added requirement that the robot must go in a circle with a radius of ~100 pixels.  Initially, I thought that I could use the circling method of the Spinbot provided in the samples, but realized that it was just constantly turning so that its circling radius was unknown.  Instead, I had to use the circle equation to calculate the points to move to.  I decided to provide the x coordinates and the radius to find the y coordinates of the target points, but this introduced another problem as the circle equation accounts for both positive and negative square roots which made the robot stall at points where the sign would change if only the Math.sqrt function is used.  To combat this, my robot changes the sign of the square roots when it reaches the points where the square root should change signs (90 and 270 degrees).

---

Conclusion


Now that I have completed these 13 code katas, I feel that I have the knowledge needed to create a competitive robot.  These exercises familiarized me with the basic movement, detection, and gun-use functions and has given me some ideas as to how to create a competitive robot.  For instance, I know that a competitive robot will need a lot of movement as dodging enemy bullets makes them waste energy and saves your own (some of the Position robots actually beat some of the sample robots by making them run out of energy even though they themselves did not even fire a single shot!).  I also understand that I will need to create a good tracking scheme so that most of my bullets hit.  Perhaps I could lead the target if it is moving to increase the accuracy of my robot's shots.  Finally, I think that code katas are a good learning device.  As said by many people, the best way to learn how to program is to actually do it and these katas provide short and interesting tasks to hone one's programming skills without the pressures provided in a project setting.  Thus, code katas like these are a good way to work on one's programming abilities off of the job.

FizzBuzz!

FizzBuzz is a simple program that can be used to test one's ability to complete basic programming tasks. To comply with the requirements of the FizzBuzz program, the created program should print out the numbers from 1 to 100 on separate lines (one output per line) with the exception of multiples of 3, for which the program should print "Fizz", and 5 where the number should be replaced by "Buzz". If the number is a multiple of both 3 and 5, the program should print "FizzBuzz". The task here was to implement this program in Java using the Eclipse IDE in an effort to familiarize ourselves with it.

---

Initial Program
Below is the Java source code that I created to implement the FizzBuzz program. This implementation took me 5 minutes and 9 seconds despite the assistance of an advanced IDE like Eclipse due to an error I made while creating the FizzBuzz.java class file. When I created the class file, I tried to specify that it should be in a non-default package, but I made the mistake of doing this in the top-level project folder instead of the src folder. This caused Eclipse to create several new folders to place the new class file in instead of creating a new package as I had intended. Consequently, I could not get the created file to run until I created a new package in the src folder and moved the FizzBuzz.java file there.

What Eclipse did when I tried to make FizzBuzz.java in a non-default package in the top-level project folder.

What the non-default package should look like.

The source code for the FizzBuzz.java class may be seen below.

---

A Better FizzBuzz
While this code does work as intended, it is not as elegant as it could be. In this format, it is impossible to use JUnit to test the file as JUnit would not be able to capture the program's output. As a result, we would need to create a function that the JUnit test can call as shown in the modified FizzBuzz program called FizzBuzz2.java.

---

The JUnit Test
With FizzBuzz2, the JUnit test can call the FizzBuzz2.fizzBuzz(int) function to test the output. The following JUnit test checks the outputs of the two end cases (1 and 100) as well as the outputs when 3, 5, 15, 25, 41, 51, 75, and 94 are passed to the function.


Fortunately, this test runs successfully and helps to assure us that the output of the FizzBuzz program is correct.

---

Conclusion
Creating the FizzBuzz program was a good exercise in using Eclipse to create a Java project from scratch and brought up an interesting quirk of the system as specifying a non-default package for a file in the main project directory caused strange behavior. It also exposes how software engineering is not a race to get a working product out. Of course, producing a working product out as fast as possible sounds good, but revising that product could lead to a much more elegant design that will save time and effort later on. Finally, the FizzBuzz program highlighted the need to take pay attention or take notes in ICS 314. I am unfamiliar with JUnit so I had no idea how to use until I looked at the notes that I took on the first day of class. Hence, it is important to pay attention to the various course materials (non-webcast lectures included!) since knowing that material (or at least keeping a reference to look up) could really help with the assignments that we will do in the future.

orDrumbox and the Three Prime Directives of Open Source Software

In our ICS 314 class, Dr. Johnson has established three criteria that open source software should be judged against to determine its quality.  Here we shall examine the quality of the open source Java project called orDrumbox using these three criteria.

---

Overview
The orDrumbox project aims to create a software drum machine with additional song composition functions.  These functions include the ability to create and modify multiple instrument tracks to create new songs and an automatic fill engine to add various patterns to the songs.  For this test, I have downloaded the setup-ordrumbox-0.9.06-win32.exe installer and the source files from the project's sourceforge.net page.

For more information, please see the project's home website.

---

Prime Directive #1
The first prime directive is if the system accomplishes a useful task.  orDrumbox appears to accomplish its task rather effectively with an easy-to-use interface that allows users to choose song templates and edit them using the various buttons and clicking on the step sequencer.  It also allows the user to play these songs, but the sound quality seems to be lacking as I heard a lot of static.  While the poor sound quality detracts from the user's experience, it is good enough to give the user a clear picture as to how the song sounds.  All in all, orDrumbox succeeds in fulfilling its task as a drum machine and a song composition tool.

The orDrumbox user interface with a pre-made song loaded.

A modified version of the pre-made template with extra cymbal hits and a new cowbell track.  The changes are in red.

---

Prime Directive #2
The second prime directive concerns the ease of the software's installation by an external user.  orDrumbox was extremely easy to install thanks to the setup executable provided which makes it so that all the user needs to do is have Java 1.6 installed and follow the installer.  The installer can even create a shortcut on your desktop for the user!  I did have some problems getting the program to launch from the shortcut, but I believe this was due to the way that my system is set up and I could easily launch it from the command line using the java -jar command or executing the Launcher script in the installation directory.  As a result, orDrumbox easily passes the second directive.

The orDrumbox installer makes installation extremely simple for anyone who has installed a Windows program before.

Finished with the installation.  The installer even includes installation progress bars like most other Windows installers!

---

Prime Directive #3
The third and final directive is fulfilled if it is easy for an external developer to understand and modify/enhance the system.  Unfortunately, this is where orDrumbox falls short.  The package of source files fails to include any developer level documentation for external developers which is definitely not desirable.  In addition, the source code itself suffers from a lack of commenting as seen below.  However, some of the function and variable names make their purposes rather self explanatory which might make understanding the source code a little bit easier.

public Element toXml(Document xmldoc) {
Element scaleElement = xmldoc.createElement("scale");
scaleElement.setAttribute("display_name", getDisplayName());
scaleElement.setAttribute("freq", getFreq() + " ");
scaleElement.setAttribute("rand", getRand() + " ");
scaleElement.setAttribute("order", getOrder() + " ");
scaleElement.setAttribute("lgr_segment", getLgrSegment() + " ");

for (int iNumScalenote = 0; iNumScalenote < scaleNotes.size(); iNumScalenote++) {
Scalenote scalenote = (Scalenote) scaleNotes.get(iNumScalenote);
scaleElement.appendChild(scalenote.toXml(xmldoc));
}

return scaleElement;
}
By looking at the source code, the problems with trying to work on this system becomes apparent.  For example, an external developer would probably guess that the function above is used to export a scale element to a XML file based on its name, but the lack of any commenting makes it difficult to know for certain without going through each line of the function.  Consequently, orDrumbox fails the third directive as there is no documentation and very little commenting which forces any external developers to look at every line of code to understand what the program is actually doing.

---

Conclusion
Overall, the orDrumbox appears to successfully fulfill two of the three prime directive of open source software.  Not only does it accomplish the tasks that it intended to, but it is also extremely easy to install on a Windows system.  On the other hand, the lack of documentation and commenting would make external development of this system rather difficult and time consuming as the only way to understand the program is to go over every single line of code.  Therefore, the orDrumbox system successfully complies with the first two prime directives, but fails to meet the third prime directive of open source software.