Continuing with WattDepot: hale-aloha-cli-tiger

As part of our continuing development with WattDepot, my group and I were given the task of adding some new functionality to another project called hale-aloha-cli-tiger. We implemented three new commands to their CLI system: set-baseline, monitor-power, and monitor-goal. Here are the commands and a short description of each:

set-baseline [tower | lounge] [date]

This command defines [date] as the "baseline" day for [tower | lounge]. [date] is an optional argument in YYYY-MM-DD format and defaults to yesterday. When this command is executed, the system should obtain and save the amount of energy used during each of the 24 hours of that day for the given tower or lounge. These 24 values define the baseline power for that tower or lounge for that one hour time interval. For example, if lounge Ilima-A used 100 kWh of energy during the hour 6am-7am, then the baseline power during the interval 6am - 7am for Ilima-A is 100 kW.

monitor-power [tower | lounge] [interval]

This command prints out a timestamp and the current power for [tower | lounge] every [interval] seconds. [interval] is an optional integer greater than 0 and defaults to 10 seconds. Entering any character (such as a carriage return) stops this monitoring process and returns the user to the command loop.

monitor-goal [tower | lounge] [goal] [interval]

This command prints out a timestamp, the current power being consumed by the [tower | lounge], and whether or not the lounge is meeting its power conservation goal. [goal] is an integer between 1 and 99. It defines the percentage reduction from the baseline for this [tower | lounge] at this point in time. [interval] is an integer greater than 0.

For example, assume the user has previously defined the baseline power for Ilima-A as 100 kW for the time interval between 6am and 7am, and the current time is 6:30am. If the goal is set as 5, then Ilima-A's current power must be 5% less than its baseline in order to make the goal. At the current time, that means that Ilima-A should be using less than 95 kW of power in order to make its goal.

It is an error if the monitor-goal command is invoked without a prior set-baseline command for that [tower | lounge]. Entering any character (such as a carriage return) stops this monitoring process and returns the user to the command loop.

Our group implemented the commands according to the specifications, and they all work as expected. There were some problems due to the previous state of the hale-aloha-cli-tiger project, but our group was able to work through it. Some of the problems were low test coverage, and bad error handling left over from the previous project. Some of these problems are still occurring, but we were not expected to fix the problems because we inherited them from the previous project.

I would say this system satisfies the three prime directives, that is, the system successfully accomplishes a useful task, an external user can successfully install and use the system, and an external developer can successfully understand and enhance the system. Despite some of the errors, the newly implemented commands are useful for retrieving energy data from the Hale Aloha Towers, and we were obviously able to enhance the system as external developers. There are also several guides on the project site that should help any external user successfully install and use the system. Based on that alone, the project satisfies the three prime directives.

Watt Depot Technical Review

As you may recall from my previous blog posts, I've been working on a command-line interface program which uses the WattDepot library to collect information about energy consumption for several residence halls at the University of Hawaii. I've learned a lot about software development throughout this project, and now I've been given the opportunity to review a similar system developed by another group which accomplishes the same task, to determine whether the system satisfies the Three Prime Directives. Here is a link to the project site I am reviewing.

Review question 1: Does the system accomplish a useful task?

Here are the available commands supported by the system:

> help
Here are the available commands for this system.
current-power [tower | lounge]
Returns the current power in kW for the associated tower or lounge.
daily-energy [tower | lounge] [date]
Returns the energy in kWh used by the tower or lounge for the specified date (yyyy-mm-dd).
energy-since [tower | lounge] [date]
Returns the energy used since the date (yyyy-mm-dd) to now.
rank-towers [start] [end]
Returns a list in sorted order from least to most energy consumed between the [start] and [end] date (yyyy-mm-dd)
quit
Terminates execution
Note: towers are: Mokihana, Ilima, Lehua, Lokelani Lounges are the tower names followed by a "-" followed by one of A, B, C, D, E. For example, Mokihana-A.

There are a few problems with the system in question. Some major functionality, including the "daily-energy" and "rank-towers" commands, is missing or broken, when it should be present and functional according to the system requirements. Furthermore, there is a bug in the "daily-energy" command that results in the error message "Date must be before today" when the given date argument is actually a valid one. In short, I could not get the "daily-energy" command to execute properly no matter what input I provided. Additionally, the system does not handle some exceptions when dealing with user-input and instead may crash if the user provides "bad" input.

The other two required commands, "current-power" and "energy-since", are implemented and function properly, except, as previously mentioned, the system may crash if the user provides bad input or incorrect arguments. Because some major functionality is broken or missing, and because the system does not handle bad user input in a graceful manner, I would conclude that the system is somewhat useful, but could definitely be improved.


Review question 2: Can an external user can successfully install and use the system?

The project site home page provides a short, clear description of the system and its purpose. Although there is no sample input and output provided on the page, it is still pretty clear what the system does based on their description. There is also a User Guide wiki page that provides details on how to download, install and execute the system. However, I found that the instructions were not completely correct, as it said the .jar file used to run the system would be in the /build/jar directory, when it was actually in the top level directory (there was no /build directory in the distribution I downloaded). There was no compilation necessary since they provided an executable .jar file, so it was pretty easy to run the system as a user. Furthermore, the download link was labeled with the version number, so users can easily keep track of what system they are using.

Review question 3: Can an external developer successfully understand and enhance the system?

The Developer's Guide wiki page provided clear instructions on how to build the system from sources, as well as the project guidelines for development, including the implementation of JUnit tests for all new features. It also provides guidelines for formatting code (including a downloadable file for auto-formatting within Eclipse), adding new issues, and verifying the build before committing changes with "ant -f verify.build.xml". I was able to determine that the developers use automation tools such as Checkstyle, Findbugs, PMD, and JUnit.

Lastly, there is a link to the Continuous Integration project build on Jenkins. From the wiki page I was able to conclude that the developers use Issue Driven Project Management as their development process, although this is not explained in detail on the page itself. There were no specific instructions on how to generate JavaDoc documentation, but I was able to accomplish this without any problems and I feel most Java developers would be able to as well. The documentation was well-written, and I felt the developers used descriptive names throughout their system, such that the purpose of a method, class or variable could be determined implicitly from its name in most cases.

I was able to generate coverage information about the system using Jacoco, and found that their tests only covered about 21% of the code. I saw that the command manager class, as well as each respective command, had its own JUnit test class associated with it, but some of the tests were not named correctly, and thus may not have been counted in the coverage. This likely contributed to the low coverage percentage.

I found that the source code followed coding standards and made effective use of comments for the most part. The code was easy to understand and I feel like an external developer could understand the system fairly easily by looking at the code and documentation.

I read the "Issues" page on the project hosting site to determine which parts of the project were worked on by each developer. I could tell that all three developers worked on the project equally by the amount of issues attributed to each member. Furthermore, I believe it would be fairly easy for an external developer to determine who to ask if they had a question regarding a particular part of the system.

I had a look at the Continuous Integration server associated with the project and saw that anytime there was a build failure it was corrected soon, or at the very least, someone worked on getting it corrected as soon as possible. It was clear that the system was worked on in a consistent fashion, and every commit was associated with an appropriate issue, which means the developers did a good job of breaking the system up into issues of manageable size.

From these results I would conclude that a new external developer could successfully understand the current system and enhance it with relative ease. I think the documentation, comments, and the readability of the source code would be pretty helpful to a new developer, and they would be able to successfully contribute with the current team to improve the system.