A Week of Configuration Management

Configuration Management

Configuration management software attempts to identify and track the elements of a system's configuration so that errors can be found and fixed. Version control is a special sub-case of this which focuses on maintaining multiple branches (development versions used for experimentation or developing new features) and the central trunk (the main version which all branches must eventually be merged with). Defect tracking systems track error reports from identification to the point at which the errors are fixed, and are part of configuration management because fixing the errors usually requires configuration changes.

To use a configuration management system, developers must first check out (download) the project from the SVN repository (the directory on a remote server where the project files are stored). Once this is done, they can edit their local copy of the project files, then commit (upload) the changed files or directories. If a developer adds new files to the project, they must be manually added to the files under version control before being committed to the repository. If others make changes, a developer must update (download new versions) the local copies of the changed files. William Wake explains it in more detail in this graphic.

As we were instructed in class, best practices for configuration management systems include verifying that the system runs and builds correctly before committing any changes. Otherwise, you run the risk of having to hurriedly fix previously undetected mistakes one after the other, as reflected in this log of commit messages:

Rev 53571: "This is a basic implementation that works."
Rev 53572: "By works, I meant 'doesnt work'. Works now.."
Rev 53573: "Last time I said it works? I was kidding. Try this."
Rev 53574: "Just stop reading these for a while, ok.. "
Rev 53575: "Give me a break, it's 2am. But it works now."
Rev 53576: "Make that it works in 90% of the cases. 3:30."
Rev 53577: "Ok, 5am, it works. For real.
Back when I said basic implementation? Scratch that."

(Source: This Stack Overflow thread)

Subversion

Subversion, the successor to the earlier CVS, is an open-source configuration management system that runs on the Berkeley Database, manages tags and branches similarly to folders, and handles all file types in the same way. It is currently an industry standard due to its centralized nature, which helps with access control issues and allows a single project leader to coordinate development; however, many in the open-source community prefer Git's flexibility and multiple workflows over Subversion' centralization.

Many GUI and command-line clients exist to access SVN repositories; I used TortoiseSVN, a Windows client. The GUI was fairly easy to use for my first assignment of revising and committing a preexisting project. For the second project, in which I had to upload my project to Google Code (about which more is written in the next section), I had a little more trouble with the command line interface, and what was ultimately more helpful than the project documentation in figuring out how to add files and do other operations was this general SVN manual, which did a good job of describing SVN's general logic.

Google Project Hosting

To complete my training in configuration management, after uploading my code to Google's remotely hosted repository via TortoiseSVN, I set about configuring the front page and some instructions for users and developers working with my robocode-tjo-meteor robot. The page I set up can be found here, and the source files can be checked out using the instructions here.

Google Project Hosting is fairly easy to add new pages to and configure settings for, using a system of simple menus similar to other Google interfaces I have used in Blogger or Google Sites.

Google Project Hosting allows users to choose Subversion, Git, or Mercurial as their configuration management system, and handles defect tracking by listing open issues on the "Issues" page. The current SVN trunk is viewable in the Source page, and the revision history is also available.

The only real issue I have with Google Project Hosting mostly deals with with element positioning:

• The tables are made with sets of ||s, not tags:Google only detects a table cell if both the opening || and closing || are on the same line (i.e., you never press enter at any point between them).
  For example, typing:
  
||Contents||
||I want this entire sentence to appear
in one table cell||

  results in:
  
  
  If you break this rule, you may end up with several scattered partial table cells. The workaround, typing the text you want to enclose as one long sentence, means that enclosing long sentences or paragraphs in table cells looks ugly in code and is almost unreadable if you use any other HTML tags or wiki markup within the table. I spent hours figuring out how to force Google to recognize the table cells before I realized that the bug was related to newline characters in this way. Google does allow the use of <table> tags, however, so there is a workaround for this.
• The anchor links:There are several things to be aware of when writing these. The support page helpfully explains that spaces need to be replaced with underscores in anchor links. Essentially, what I discovered was this:
  
// In this case I am trying to make an anchor link to header == Foo Bar ==
[# Foo Bar ] // This creates a link to the main URL of the page itself, and reloads it instead of going to the anchor. In some cases it does not work at all. The preceding and trailing spaces are not needed even though they are in the header.
[#Foo Bar] // This will not work either. As mentioned, the space needs to be replaced with an underscore.
[#Foo_Bar] // This will work.

  If you are mostly using this to make a table of contents as I did, there is a faster piece of built-in wiki code that does the job:
  //Set the depth to specify how many layers deep you want the contents to go.
  
• You cannot import images directly:Blogger allows you to import pictures from within the editor and host them on Picasa, in addition to embedding image links to pictures you have hosted elsewhere. This is not possible in Google Code. Though I there are definitely reasons to prefer this approach (Picasa's limitations, privacy concerns, or Blogger's arbitrary display sizes of "large", "medium", and "small"), a similar feature might be nice as an additional option.
  

Despite these minor issues (some of which were aggravated by my misreading of Google's support page), Google Code seemed to provide a decent level of services for being a free service and was an easy way for me to learn the basics of version control in a controlled setting, without the risk of damaging a real enterprise project - and demonstrated the ease with which I could use Subversion systems to store personal projects as well, though perhaps not quite at the level of Joey Hess.

Some Lessons In Software Engineering

It's been an interesting semester of ICS 314 so far, and since it's about the middle of the semester (and time for our first midterm) I decided to summarize some of what I've learned over the past few weeks.

Validation and Verification

1. In software review, validation is the process of checking that code is being made for the correct purpose, and verification is the process of checking that code is made correctly.
   Here I define these four validation and verification methods, and specify whether they are static or dynamic: load testing, defect testing, software inspections, and static analysis of source code.
   
• Load testing (Dynamic): Dynamic tests, unlike static tests, test the program by running it. Checks for errors in scalability, performance, and reliability.
  
• Defect testing (Dynamic): This is another form of static testing that checks for functionality errors.
• Software inspections (Static): Manual inspections of code by other developers. This refers to the formal process of "inspection" developed by Michael Fagan (described in more detail by "The Software Experts" here), as well as more informal code reviews and peer reviews. In all of these processes, other trained developers examine a project's code for implementation errors and requirement satisfaction.
• Static analysis of source code (Static): Examines the source code by looking for control and data flow issues, without running it.

Testing and Branch Coverage

2. One of the factors used by tools like Jacoco to determine the coverage of a program's test cases is control flow coverage - whether and how many of your control statements (if, else, etc.) are ever executed. I explored many issues of control flow coverage as I designed my test cases for the Robocode project.
   So, what are the three types of control flow coverage?
   
   • Branch coverage: Testing evaluates each conditional as true and false.
     • I made an attempt to provide branch coverage in my method unit tests. In what was probably at best a confusing design decision, I created and tested a method called whichWallOrCorner that returned one of nine integer values based on whether the robot was near a wall, near a corner, or near neither. What made this complicated to test was that, in accordance with branch coverage, the JUnit test needed to check all possible return values, as did every other method which called this method. In effect, each assertion in the JUnit test case evaluated one of the conditionals as true and all of the other conditionals as false. The distanceToWallOrCorner method, which depended on whichWallOrCorner, was just as long as the method it relied on; in effect, every piece of code that used the whichWallOrCorner method had to handle all nine possible return values in some way.
   • Loop coverage: Testing executes every loop 0 times, once, and more than once.
     • Apart from the main while(true) loop, the robot did not have many other loops in its code. The only way to check the while(true) loop and its sub-loops was to run acceptance tests which pitted the robot against other robots. Even so, these could only verify victories or proper method execution, not loop execution.
   • Path coverage: Testing executes all possible paths through the program.
     • Once again, as most loops were nested within the the while(true) code, it was not possible to test each nested loop directly, or even indirectly via the acceptance tests. For the method unit tests, it was much easier to force all possible paths to execute by passing appropriate variables to the method.
   My Robocode experience is described in more detail in this previous post.
   For at least the next few months, a more current version of my robot can be found here.
   
   

   Unit Testing for Input which is a Value

3. How should unit tests be written for methods which take values as input?
   
   Unit tests for methods that take values as input should, at minimum, test the method's behavior for the maximum legal value, the minimum legal value, an empty value, a value somewhere within the range of legal values, and an illegal value.
   
   Alternately, the minimum, according to equivalence partitioning, is as follows: once the values have been divided into partitions (ranges of input), only one test is needed per partition (e.g., one partition holding illegal values that are too low, one partition holding all the legal values, and a third partition after it which holds illegal values that are too high). In equivalence testing, it is thought that all the test cases for values within a given partition are the same - so only one value in each partition needs to be tested.
   



Pitfalls of Automated Quality Assurance

Just as a car company would use a wind tunnel to test aerodynamics but would use a focus group to test visual appeal, in software engineering there are some things manual testing does much better than automated testing.


4. Why is it a bad idea to use automated quality assurance to verify product requirements?
   
   Automated quality assurance is not smart enough to know whether something implements design requirements. It can only check if code is syntactically correct (e.g., Checkstyle, PMD) or creates usable bytecode at build-time (e.g., FindBugs).
   
   Only manual quality assurance can find problems related to the project requirements - a machine can check whether code is error-free, but only humans can reliably judge whether or not code is useful. My Robocode robot is a good example of this - despite its being very ineffective, even against most of the sample robots, the current version passes all of the FindBugs, Checkstyle, and PMD tests with no errors.
5. Why does automated quality assurance sometimes generate false positives?
   
   Automated quality assurance often flags code as a "problem" because it thinks it is a stylistic error, even if you intended it to work this way.
   
   I encountered this issue often when writing my JUnit tests. PMD would repeatedly flag my tests with UseAssertSameInsteadOfAssertTrue errors. In an ill-advised attempt to make this "go away", I replaced all the assertTrue methods with AssertSame. However, because this checked object equality, all of my tests that compared the values of numbers failed. As I found out from Stack Overflow, assertSame fails for any integers larger than 128, and based on personal experience, it does not work with doubles at all. I then converted all the assertions to assertEquals and added statements to print the purpose of each test. This caused all the tests to throw JUnitAssertionsShouldIncludeMessage errors in PMD. The errors finally went away when I converted the assert statements to the three-argument form of assertEquals, which includes a message. The code worked as expected before, but PMD refused to validate it until the "correct" test was used. Of course, one of the benefits of automated quality assurance is that it can detect problems the developer is too inexperienced to notice, so it is more probable that PMD was correct and my code was written inefficiently.

Going In Circles And Then Some: Preparing for a Robocode Tournament

Project Overview

The robot I was attempting to design for the Robocode tournament would have avoided hitting walls altogether, and would have been able to maintain a basic lock on its target. Neither of these goals was accomplished to any useful extent.

Design

• Movement

Ideally, the robot was to have moved 100 pixels each turn, turning itself perpendicular to the headings of any enemies encountered and turning back before hitting walls where possible. I attempted to do this via the avoidBounds method, which was intended to turn the robot away from walls and thus avoid collisions with the walls entirely. As far as I can tell, this instead caused freezing problems whenever the robot managed to be positioned perpendicular to a corner, and in some other cases I was unable to define.

• Targeting

Ideally, the robot was to have rotated its radar 180.0 degrees per turn, turned its body to be perpendicular to an enemy robot once it was scanned, logged its opponent's name, then begun scanning in smaller 22.5-degree intervals as long as it continued to detect that same opponent. Once that opponent was destroyed or had not been seen for two scans, it would resume scanning in increments of 180.0 degrees. In reality, the robot lost targeting locks almost constantly, as its other behaviors caused it to turn too frequently to maintain a consistent heading or back-and-forth pattern of strafing.

• Firing

The robot implements a basic bullet-power calculation algorithm based solely on distance, starting at the maximum of 3.0 for anything less than 100 pixels away, dropping from 2.9 to 2.0 for anything 100-300 pixels away, then to 1.9 to 1.0 for anything 300-500 pixels away, then to 0.9 to 0.5 for anything more than 500 pixels away. It fires whenever it detects the robot it is currently targeting, and targets the same robot for the duration of at least three 22.5-degree scans before giving up and looking for a new target.

Results

(Each robot was fought for 10 rounds.)


Meteor's lack of predictive targeting means that Walls has moved out of range by the time Meteor aims its cannon at where Walls used to be; Meteor has no way of accounting for drastic shifts in direction or velocity on the part of an enemy robot.

Robot Name	Wins Against	Losses Against
SittingDuck	10/10	0/10
Virtually all robots can beat SittingDuck.
Tracker	1/10	9/10
Meteor's primary weakness against Tracker is that it takes too long to scan for changes in motion (Tracker hardly scans at all once it has a lock), and thus fires much less often than Tracker. In addition, when this robot loses track of a target, it completes a 180.0-degree radar rotation, leaving it vulnerable to attack.
Corners	0/10	0/10
Meteor's avoidBounds method backfired here, frequently causing it to spin in circles without firing or moving while Corners swept its radar across the battlefield in increments.
Fire	0/10	0/10
Once again, the problem was that Meteor took too long to aim and fire,getting only a fifth the bullet damage of Fire. Meteor also froze repeatedly in this match.
Crazy	3/10	7/10
Meteor did not perform predictive movement analysis, and had no way of estimating Crazy's movement pattern, whatever it was. I am not sure why Meteor won against Crazy at all.
SpinBot	0/10	10/10
Meteor actually dodged several of SpinBot's projectiles, but it failed to score any hits of its own and usually got stuck against a wall after about thirty seconds, thanks to its freezing bug.
RamFire	2/10	8/10
Once again, Meteor's need to make large turns and radar sweeps each time it lost a targeting lock did it in; this made it easy for RamFire to push Meteor into walls or otherwise obstruct its movement.
Walls	0/10	10/10

Testing

My tests consist of two acceptance tests, TestMeteorVersusCorners and TestMeteorVersusFire, both of which the robot fails (see the Results section); one behavioral test, TestMeteorFiring, that checks whether Meteor.calculateShotPower is functioning correctly; and three unit tests (UnitTestWhichWallOrCorner, UnitTestDistanceToWallOrCorner, UnitTestNewXAndY) for the methods Meteor.whichWallOrCorner (which returns an integer code based on whether the robot is near a wall or corner), Meteor.distanceToWallOrCorner (which calls whichWallOrCorner itself, and determines the distance to a wall or corner) and a combination unit test for the very similar Meteor.newX and Meteor.newY methods, which calculate the point that a particular motion will cause the robot to drive to. UnitTestNewXandNewY does not work, however, due to what are probably errors in how I assumed it was supposed to work.

Lessons

The Robocode design process has revealed a harsh truth about my coding style: specifically, that it tends to produce a lot of code, most of which performs as expected, but most of which goes towards performing some extremely complex task (avoiding walls) which in the long run is not very important. In addition, the sheer length of my code virtually guarantees problems like Meteor's mysterious freezing episodes, which could come from any number of points in the code which control movement and which do not seem to share any common factors. Thus, I have a robot with about 400 lines of code (excluding comments) that cannot beat any of the sample robots with any sort of reliability, is still incapable of detecting when it is near a wall and stopping, and shoots straight but on average takes longer than most of its opponents to do so. The major problem is the freezing bug, which I have repeatedly failed to fix over the course of the last two days. If I had tried to do this over again, I would have spent less time trying to reinvent the wheel and more time modifying example code, as my attempt to implement a wall-avoiding function took so much time there was little left to actually test anything else.

Apache Ant Code Katas: Learning A Build System In One Week

Introduction

Build systems are software packages which help software developers by automating project tasks that need to be done repeatedly, such as compiling source code, running compiled code, generating documentation, and packaging a system for distribution. All of these tasks do not take much time to do by hand for small projects, but for large academic or enterprise projects with hundreds or thousands of files, doing anything manually is virtually impossible. Apache Ant, a free build system commonly used in enterprise, carries out all of these tasks and more by using Java libraries to process instructions in user-created XML files. Users can extend Ant's functionality by writing their own libraries or by combining it with dependency-management tools like Ivy, which download whatever third-party libraries are needed to run a given piece of code, then save them locally. For this exercise, I completed several code katas designed to teach me some of the basic functionality of Ant 1.8.2. Each kata required me to create a specific filename.build.xml file, which would contain processing instructions for Ant.

Kata 1: "Hello World"

In the time-honored tradition of everything in computer science, I started here. The objective here was to teach use of the <echo> element to print informative text to the console. This did not take very long.

Kata 2: Properties Are Immutable

This kata was intended to teach procedures for defining properties, and to demonstrate that properties cannot be changed once defined within a build file. I defined a property, then attempted to define another property with the same name. As intended, this had no effect whatsoever, and the <target> which printed the property value printed the first value which was defined.

Kata 3: Dependencies

In Ant, the "depends" attribute of a <target> element specifies which targets must be completed before a target's instructions will be executed. This is used to make sure that any prerequisites for a target to run correctly (e.g., compiling code before trying to run it) can be carried out. This kata required us to print the name of the target as it was being executed, and I spent a few hours fruitlessly trying to print each target's "name" attribute before discovering that it might not be possible without Javascript workarounds. In the end, I defined properties with the same names and values as the targets they were defined within, and settled for <echo>ing those.

Kata 4: Calling the Java Compiler on HelloAnt

This exercise used a simple Java program which printed "Hello Ant" to the console. Here, within a "compile" target, I defined two properties: paths to a source directory (where the .java file was) and a build directory (where the .class files would be output to). I then used the <javac> element, which would tell Ant to run the javac compiler given the specified directories as parameters. This kata was still fairly easy. More importantly, running this script repeatedly was faster than having to specify the directories each time I ran javac from the command line.

Kata 5: Running HelloAnt

This exercise called for importing the .xml file from Kata 4 and using its "compile" target to compile the system before running it. As it turned out, defining the directory paths in Kata 4 meant I could easily reuse them here, as importing a file also imports all of its defined properties. Using the same principles outlined by the Dependencies kata, I made the "run" target dependent on "compile". The hardest part of this was guessing at how to write the <java> element's "classname" attribute for java files in a package, which I couldn't find an example of in the Apache documentation. At first, I tried to treat the class name as a series of nested folders (/edu/hawaii/ics314/filename.extension), which is how it appears in the file system. After several variations on this, I learned that ant requires that the classname be written using its Java format (edu.hawaii.ics314.filename, no file extension).

Kata 6: Making Documentation for HelloAnt

This kata demonstrated the use of the <javadoc> element, within a target that was dependent on the <compile> target, which was imported. This ensured that the Javadoc files would only be generated if the source code actually compiled. The <javadoc> element also allows you to control what information is included in the javadoc by setting attributes such as "author" or "overview" to "true". Generating documentation manually is always tedious, and the attribute options are less tedious to use than typing each option individually (every time you needed to revise the documentation) and running Javadoc from the command line.

Kata 7: Cleaning the Software Package

This exercise required me to modify the .xml file from Kata 4 to add a target which deleted the "build" directory generated by the "compile" target. This was intended to teach the use of the <delete> element, which instructs Ant to delete the directory specified in the "dir" attribute.

Kata 8: Package HelloAnt for Distribution

I had a recurring problem when I first tried to implement this kata: as required, it would delete the build directory, but it would mysteriously include the build directory in the .zip file it created for distribution. Eventually, I realized that because I had to create the build directory again to store the .zip file in build/dist, it was always saving the empty build directory into the .zip file. I fixed this problem by modifying some code from a class example to first save the .zip file to a temporary directory, copy it over to the desired directory, then delete the temporary directory. The main lesson here was to use the "excludes" attribute to exclude the build directory from the distribution. Regardless, manually excluding unnecessary files before creating the distribution directory would have been an annoyance for a small project like HelloAnt, but impossible for any enterprise project of moderate size.

The second requirement was to make sure that unzipping the directory from the command line would preserve the original directory structure. This was simpler and involved creating a directory with the same name as the current directory within the distribution directory. Removing the build files from the distribution not only reduces its file size, but makes sense in light of Prime Directive 2: forcing other developers or users to build the system using the build files you've provided is a good way to verify that others can install and use your system.

Ant / Ivy and the Three Prime Directives

As free software packages which work together, Ant and Ivy are fairly easy to install as long as one follows the site instructions (Prime Directive 2), and automating otherwise tedious tasks easily fulfills a useful task (Prime Directive 1). While I can't say that I have personally tried to extend the system, I was able to complete most of the katas without going outside Apache's documentation, which does go some of the way towards fulfilling the third prime directive as well. It is also worth noting that despite my initial problems on some of the later katas, all of the tasks I was trying to instruct Ant to perform would have taken just as long, if not longer, if they had to be performed by hand and/or directly from the command line over and over again. Build systems may take time to learn, but a little time invested up front here will always save more time in the end.

Final Thoughts

Though I wouldn't claim to understand everything about Ant at this point, the code katas did force me to learn enough to understand its basic capabilities and encourage me to look further into its other features. The extensive use of custom XML markup for interpretation by Ant and Ivy's Java libraries demonstrates to me that XML, as a user-defined markup language, is as useful as a developer wants it to be. Learning new software tools or APIs quickly is always a little like jumping into a pool; code katas won't get you into the deep end right away, but they can teach you enough to slowly move into deeper water and not drown.

The Robocode API: Rapid Learning With "Code Katas"

Introduction

Learning and practicing new computer skills (a programming language, an IDE, an operating system, etc.) is a task that is often frustrating at best and intimidating at worst, especially when one is having trouble learning the system at its most basic levels. The philosophy of code katas, a form of practice with a name borrowed from Japanese martial arts, seeks to break the learning process down into a series of repeated drills, each one slightly more complex than the last. As the developer completes each drill, he or she gains essential skills along the way. This kind of "effortful practice" produces results faster than unfocused practice because it is focused around specific tasks, ideally just beyond one's current level of competence.

With this in mind, I set out to complete thirteen code katas for the Robocode API:

1. Position01: The minimal robot. Does absolutely nothing at all.
2. Position02: Move forward a total of 100 pixels per turn. When you hit a wall, reverse direction.
3. 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.
4. Position04: Move to the center of the playing field, spin around in a circle, and stop.
5. 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.
6. Position06: Move to the center, then move in a circle with a radius of approximately 100 pixels, ending up where you started.
7. Follow01: Pick one enemy and follow them.
8. Follow02: Pick one enemy and follow them, but stop if your robot gets within 50 pixels of them.
9. Follow03: Each turn, Find the closest enemy, and move in the opposite direction by 100 pixels, then stop.
10. Boom01: Sit still. Rotate gun. When it is pointing at an enemy, fire.
11. Boom02: Sit still. Pick one enemy. Only fire your gun when it is pointing at the chosen enemy.
12. 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).
13. 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).

The Robocode project, once managed by IBM and now an open-source, community-driven effort, provides a way to program armed virtual robots and pit them against each other. Robocode robots are controlled by programming three types of behavior: movement, radar scanning, and firing. Though the core concepts are simple, the API is versatile enough that in the hands of experienced developers, Robocode battles can become a serious business indeed.

Look at this genetic algorithm, now look back at mine. Sadly, my code lacks complex algorithms. But the idea behind the code katas is that, with practice, that code is what my code could look like. Each group of katas emphasized a specific skill, whether finding specific points on a map, circling a particular area, tracking and picking targets from among multiple enemies, or controlling the power of the robot's shots based on information acquired about enemy robots.

The first three position methods were easy to implement. The fourth took a little more work, but finding the center was fairly easy after writing methods to calculate the angle between the robot and the center, and the distance of the straightest path to the center, and the sixth was just a variation of the fourth. The fifth method was the hardest of the group for me, and it took a while before I realized that it was returning the wrong angles because the robot was not accounting for its own previous turning when calculating the turn angle. I made heavy use of the Math.atan2 method here, as it was easy to retrieve the x- and y-distances between two points for use in calculating the angle.

The Follow robots were easier to write, since most of the data needed to match the headings of enemy robots could be obtained from pre-made methods, especially the method which retrieves a scanned robot's name for easy tracking. Follow03 was easily implemented by causing the robot to scan continuously for enemies, store their data, and compare the results after each scan.

Most of the Boom robots were also quickly written; Boom01 and 03 only needed to fire automatically. Boom02 was also easily handled using the getName() function. I am still not sure whether or not I implemented Boom04 correctly; it lost its "lock" on the target frequently,
and occasionally aimed in the opposite direction of its target's motion. The problem was probably related to correcting for differences between the gun angle and the robot's heading, something I did not quite get the hang of; since each exercise in a group was based on previous ones, Boom05 could be the exercise where sloppily designed but still previously workable methods finally became unusable.

Overall, the "code katas" were easy ways to pick up basic programming skills, and even some of the errors along the way pointed the way to competitive strategies I might be able to use in the future.

FizzBuzz in the Eclipse IDE

A "Simple Program"

"FizzBuzz programs" are tests of basic programming ability proposed by Imran Khan in the article "Using FizzBuzz to Find Developers who Grok Coding." Khan designed the FizzBuzz tests after meeting many programmers who struggled to solve simple problems, and argued that the tests could be used to weed out weak programmers during the interview process. The FizzBuzz challenge is as follows:

Write a program that prints the numbers from 1 to 100. But for multiples of three print "Fizz" instead of the number and for the multiples of five print "Buzz". For numbers which are multiples of both three and five print "FizzBuzz".

In my ICS 314 class, Professor Johnson assigned us the task of writing a FizzBuzz program in Eclipse, an integrated development environment (IDE) for Java developers, and measuring the time it took to do so. The below program was written and checked for correct output in a time of  5 minutes and 35 seconds:

Eclipse

I found Eclipse easy to use, as I already had prior experience with this IDE from my ICS 211 class. Eclipse has many useful features, including refactoring, automatic error detection, and easily compiling/exporting .jar files.

While using Eclipse in ICS 211, one of the most common error notifications that I saw was "Cannot make a reference to the non-static method "foo()" from the type "bar". In FizzBuzz, when I tried to call determineOutput(int i) in main, this error appeared again. Since this was a timed exercise, I just made the method static; I knew that if I did, Eclipse would stop bothering me and let the program run. I knew this because, in ICS 211, I had gotten into that exact habit of declaring many methods static just to make Eclipse stop bothering me. As it turned out, Professor Johnson went over this issue on the first day of class: static methods should be used as little as possible because, as described by Miško Hevery on the Google Testing Blog, they make testing more difficult.

A Lesson in Coding Techniques

In the case of the FizzBuzz program, we were shown how to get around having to use a static method by instantiating a copy of the FizzBuzz class within the main() method of the FizzBuzz class itself:

In this case, the non-static version of determineOutput can be accessed by any class (including a tester) that instantiates a copy of the FizzBuzz class. This can be done without causing compiler warnings or other problems when FizzBuzz.determineOutput(int i) is called:

To me, the FizzBuzz static method example is related to one of the lessons of software engineering: code must be written not just to finish a task, but to ensure that you and others can easily understand, test, and improve it. The attitude of "planning takes too long, just finish this" was a major part of my programming process when I took 211, and it probably resulted in some of the long nights of testing I experienced in which I struggled to find all of the logical bugs I had unintentionally introduced. This stronger emphasis on planning clearly sets apart a higher-level class like ICS 314 (which focuses on developing more efficient and elegant methods of engineering software) from a more basic-level class like ICS 211 (which teaches basic methods of implementing standard Java classes and data structures). In a class like 211 you are given tools and must be taught how to use them without hurting yourself, but in a class like 314 you learn how to build precisely and build to last.

The Three Prime Directives of Open Source Software: PDF Split and Merge

Introduction

In the world of open-source software, the "Three Prime Directives" define the characteristics of a true open-source project. To fulfill the first directive, "the system must successfully accomplish a useful task." To fulfill the second prime directive, it must be true that "an external user can successfully install and use the system." The third directive is fulfilled when "an external developer can successfully understand and enhance the system." Fulfilling the three prime directives is important for an open-source project because it ensures that users and other developers can contribute bug reports, feature requests, and their own add-ons to the project, thus enabling the developers to better understand the needs of their customers and improve their system.

Sourceforge

Sourceforge is a well-known source code repository for open-source software, offering hosting and version-control services and providing a means for end users to directly contact development teams with bug reports and other feedback. ICS 314 is a Java-oriented class, so we were asked to find and review a Java-based project.

PDF Split and Merge

PDF Split and Merge's homepage describes itself as "... an open source tool (GPL license) designed to handle pdf files." Its GUI is written in Java Swing, and the command line interface is also based on Java.

The Windows installer for PDF Split and Merge can be found at http://sourceforge.net/projects/pdfsam/, and the other installers can be found at http://www.pdfsam.org/?page_id=32.

Prime Directive 1

PDF Split and Merge (referred to as PDFSam from here on) provides a wide suite of tasks related to the manipulation of PDF files. These include splitting and merging the pages of existing PDF files, rotating PDF pages, and combining multiple sections extracted from PDFs into a single new document. Most other programs which provide these functions are proprietary (e.g., Adobe Acrobat or Adolix Split Merge PDF), so consumer demand does exist for the useful task which PDFSam accomplishes.

Prime Directive 2

Ease of Installation

PDFSam was easy to install, and though there were problems with the installation, they were quickly fixed. The Downloads page features "basic" versions for Windows, Mac OS X, and a .zip file, which contains all the files that the .exe installer creates. The program requires Java SE 2 version 1.6 or higher to run. The site also offers an "enhanced" version that is free (if you compile the code yourself) or available as a regular installer for "a single donation of any amount." I installed the basic version.

Installing From A .zip File

Once the files are extracted, the program is easily run from the pdfsam-2.2.1.jar file. For some reason, the folder still contains a useless "pdfsam-starter.exe" file, exactly like the folder created by the .exe installer. The .exe installer had its own set of problems, which are covered in the next section.

Using the Windows Installer

The .exe installer ran with no problems on my Windows 7 machine, but the application failed to launch from the startup menu. I ran a compatibility check, which recommended running it using Windows XP SP2 settings. This caused the program to open and crash, saying it had failed to find "pdfsam-2.2.1.jar." The installer had created pdfsam-2.2.1.jar in the installation directory, but for whatever reason pdfsam-starter.exe couldn't detect it.

The readme.txt file included with the installation stated the following:

"Installation: Unzip the archive into a directory. Double click pdfsam-2.2.1.jar or open a console a type the command "java -jar /pathwhereyouunzipped/pdfsam-2.2.1.jar"".

Following this instruction successfully launched the program. Though the program runs from the .jar file, and readme.txt does tell the user to run the .jar file and not the nonfunctioning launcher "pdfsam-starter.exe," there are problems with this approach. Any user who used the .exe installer would not be able to easily access the program from the start menu, which only provides a link to the broken "pdfsam-starter.exe" file and no link to the .jar file that actually runs the program.

The program isn't unusable by any means, but the need to read documentation to get around a broken launcher implies that the problem is known but still not addressed, and doesn't satisfy the first prime directive's requirement for ease of installation.

Ease of Use

I was able to use most of PDFSam's PDF manipulation features without consulting the included instruction manual. It has five basic functions: "Alternate mix" (which can reverse the order of a document's pages or mix pages from documents at specified intervals), "Merge/Extract" (which lets you merge specific parts of PDFs), "Rotate" (which rotates all pages in a document in increments of 90 degrees), "Split" (which divides a document into pieces), "Visual document composer" (which lets you take individual pages of multiple documents and merge them into a single document) and Visual reorder (which lets you change the order of pages in one document). I tested PDFSam's basic functions with multi-page PDFs of lorem ipsum text and found the features easy to use.

The PDFSam GUI.

The command-line features are less easy to use, but still usable by following the instructions in the tutorial PDF or its wiki (command line instructions shown):

The mistake to avoid making here is to assume that "options" and "required" mean the "options" and "required" arguments that apply to "command." Actually, "required" covers all the arguments exclusive to "command," whether the arguments are specified as optional or not. After an hour or so of working through my confusion, I successfully did this:

The command line output produced by merging two PDFs.

To be fair, my mistake was a careless one, and command-line tools aren't usually intended for casual users (who will mostly use the GUI), so any difficulty on the part of the command-line tools doesn't detract much from the program's overall usability. PDFSam still mostly fulfills the second Prime Directive as it relates to ease of use.

PDFSam does a mixed job of fulfilling the second Prime Directive, and is easier to use than it is to fix it after it installs.

Prime Directive 3

PDFSam does a good job of fulfilling the third Prime Directive. Source code and developer-level documentation is easy to find on the project's official (non-Sourceforge) site. The source code is available on the Downloads page. Each Java source code file begins by making developers aware of their modification rights under the GPL, and each file includes cross-references to other Java files. This is demonstrated by the code excerpt below:

Developer-level documentation is provided on the Resources page. Java documentation is provided for both the basic and enhanced version's APIs, and changelogs and software requirements are also available. The Resources page also provides links to request features and access its SVN repository. Bugs are reported in the forums. Developer documentation is easy to find, the source code is readily available, and changes are publicly proposed and discussed, fulfilling the Third Prime Directive.

Conclusion

Despite my problems with PDFSam's Windows installer, its GUI is easy to understand and provides many useful ways of manipulating PDFs. Developer documentation, source code, and forums for communicating with developers are easily accessed. Overall, PDFSam fulfills many of the requirements of the Three Prime Directives.