Hale Aloha CLI v2

Taking upon another group's code is no easy task. The difficulty can range from perplexing to hair-pulling. Thankfully, taking on Team Pichu's implementation of a WattDepot Command Line fell into the former category (our friends at Team Teams, who inherited the system previously built by us at Team Cycuc unfortunately fell into the latter category.) As previously blogged about, the level of extensibility is made through open-sourcing one's code and providing thorough documentation. Another important part of making code easily extensible is simple, comprehensible code, which Team Pichu has provided. The process of extending it was no harder than creating a new Command that extended the provided interface and adding it to their processor class (which used branching rather than enumerations, which, while less elegant and efficient, is easier to understand.) As such, the members at Team Cycuc: Yong Hong Hsu, David Wilkie and I successfully create Commands that extended Team Pichu's implementation, though issues with communication meant for an implementation that does not meet specifications.

In many ways, it was easier to work with an existing implementation since issue-driven management means that one can easily assign tasks via Issues in Google Project Hosting, but the problem with Issues is that just because they're there doesn't mean that they're correct and that communication isn't required. The problem with our implementation came from poor planning and coordination, and assumption that all commands do not depend on each other. If we as a team had looked at the specifications thoroughly, we'd know what each of us had to do at what time. Monitor Goal, assigned to Yong Hong Hsu, relies on set-baseline and monitor-power to successfully monitor whether a source achieves a goal, but fails to correctly integrate the methods coded by David and I. In retrospect, my implementation wouldn't have worked as a monitoring-device since the power isn't automatically updated while MonitorPower.run() is running, though an Issue wasn't raised by Yong Hong nor was I contacted in any other method.

With this in mind, I can easily say that our build is a partial failure in terms of the first Prime Directive "Does the system accomplish a useful task?" since it provides partial functionality, as it sets baselines and monitors power, but doesn't allow for the user to monitor whether a tower lowers their energy consumption to a certain percentage of the baseline. It does, however, print out the power at a regular interval such that a user itself can monitor the power of a WattDepot tower.

The ease of which I had implemented MonitorPower however (it took less than a day of coding), shows that the second two Prime Directives are achieved, all credit to Team Pichu. In comparison to Team Teams reaction to taking over our code, their code was incredibly easy to understand due to its simple constructs, meaning that the KISS principal should be used always, especially if one expects to open-source their project to provide for more functionality from other users.

UPDATE(8:45 am): After much running-around-with-hair-on-fire coding, I've gotten monitor-goal and monitor-power to work roughly as specified. It can be found here , it's a last-minute-heroics edition of the interface, since that's what I had to do.

Technical Review: Hale-Aloha-CLI-Pichu

Technical Reviews are rigorous testing of a system, such that all aspects of the system are scrutinized, pointing out errors that the developers themselves wouldn't have noticed. This review will be of a group who had developed a command-line interface for the WattDepot server provided by Professor Philip Johnson, a task we were also recently charged with. As such, they were put under the same development conditions as us, incorporating Google Project Hosting and the Jenkins server found at http://dasha.ics.hawaii.edu:9859/ to use Continuous Integration and Issue Driven management.

Prime Directive 1: Does the system accomplish a useful task?

The WattDepot project and server, for those unfamiliar with it, is a project started by Professor Philip Johnson for the continuous monitoring of power consumption in the dormitories on the campus of University of Hawaii at Manoa.  The system makes use of multiple sensors installed throughout the dormintories, each keeping track of their individual section.  This information is then provided by the user by an API implemented in Java.  This API was used by Team Pichu to provide for the CLI being assessed in this review.  Having such an easy interface, this would allow the user to easily assess the energy consumption of a specific area in a building.  This would allow for corporations to conduct Energy Audits which is a major part in reducing our energy consumption and dependence on foreign oil, as mentioned in my previous blog post.  As such, the task provided by the CLI is incredibly useful.

Prime Directive 2: Can an external user can successfully install and use the system?

 The command-line provided by Team Pichu is an excellent way of interacting with the WattDepot API.  Although many programs nowadays make use of GUIs, command-lines are still an efficient way to control a program.  In this case, we are provided with a .jar file that can be easily run via the command-line with java's -jar option.  The client is fairly easy to understand from the user's standpoint, especially with the help of the documentation on Pichu's homepage as seen in this screenshot.

Having such easy documentation allows the user to quickly understand how to query and get meaningful data from the WattDepot servers.  After downloading the distribution from their site, I quickly got all four commands running within a minute:

Besides the help page, however, the feedback provided to the user when given bad input is lacking.  Outside of notifying the user that the wrong number of arguments has been passed, the program does not specify what is wrong with an argument.   For instance, if a person mistyped the source name, or if the person provided an invalid date (like a date in the future) the program would simply state that an argument is invalid.  Better feedback would be to specify what is wrong with a provided input without the user having to consult the help page.

Prime Directive 3: Can an external developer successfully understand and enhance the system?

Being developers, the spirit of providing a functional system would also be to provide something that can be easily extended, providing even more function.  Team Pichu has done the right thing when it comes to their code and provided their code for free on their Google Project Hosting site.  All one has to do in order to enhance the system would be to the SVN revision control system.  Google's functionality allows for the user to simply input 'svn checkout http://hale-aloha-cli-pichu.googlecode.com/svn/trunk/ hale-aloha-cli-pichu-read-only' into the command line to download the system into the user's current path.  From then on, the DeveloperGuide provided by Team Pichu provides simple instructions to build the system, their build tools they've used, and how to generate the documentation for the system, though none on extending it (importing it into Eclipse, for instance.)

Upon importing it into Eclipse, a dependency for the WattDepotClient is broken, as well.  The .settings file provided by the team for use in Eclipse provided a literal classpath instead of a local classpath relative to the project's root.  As such, the build path specified by the system was not the same on my system, making compilation and extension impossible.  Luckily, the problem could be remedied by specifying the jar to be relative to the project, which would solve it for all environments.

The code itself is thoroughly documented with Javadoc, though there is little explanation as to the strategy implemented.  For instance, even after generating and reading through the javadoc, I'm still not sure how the Command classes determine a valid source (it seems like it uses regex which generally isn't very readable or understandable to anyone who didn't implement it) or why they use the Date and SimpleDateFormat classes to check and generate timestamps.

The Developer Guide provides excellent instructions to continue their method of quality assurance.  Their method involved Automated Quality Assurance tools CheckStyle, PMD and Findbugs which was activated with their provided ant build file verify.build.xml.  Locally they emphasized the importance of using the provided tools to ensure a standardized, working code.  They've also provided for a server using the Jenkins quality assurance tool to monitor their repository.  Jenkins, using the same ant build file, monitors the state of the system and emails the developers in charge if any part of the verification system fails.  This would allow members to quickly troubleshoot and restore the system to a working state in as little time as possible (looking at the previous changes to the system so far, each problem was fixed in roughly 20 minutes, which is better than, say, changing the system then running it later that day only to realize that it doesn't work.

The developer guide also emphasizes to continue the correctness of the program using JUnit test cases.  Looking at the test cases and running the included jacoco build file, the team extensively tests the various commands using both good and bad input, resulting in a well-tested system with 85% of the instructions tested.

The team also had used Google Project Hosting's Issue feature to document the build process and relate each change to the source to a specific Issue.  Looking at the issue and previous commits, it seems that two out of three of the team members had implemented most of the code, but did so in a way that is easy to see what changes were made and what issues related to it.

In all, even though some documentation were lacking and through a little troubleshooting, the system seems to be able to be extensible.