Hale Aloha CLI Technical Review

Looking back to my first blog post about Open Source Software and the Three Prime Directives, the goal of any open source software should be to fulfill these directives to ensure maximum usefulness to both end-users and external developers. To do that assignment properly, I had to find open source software that fulfilled the three prime directives which proved difficult. In my last blog post, I talked about my experiences when tasked with developing a command-line interface using the WattDepot client. This blog post will explore the process of performing a software technical review on a similar command-line interface developed by another team.

The following is the technical review my team put together while evaluating hale-aloha-cli-cycuc with respect to the three prime directives.


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

To answer this question, you must download, install, and run the system under review. You should exercise the system with a variety of values for each of its possible commands. You want to discover if there is any functionality that should be present that is not present. You must document what functionality is present in the system and then come to a conclusion regarding the usefulness of the system.



When we initially ran Team cycuc's .jar file there was a slight problem as it couldn't successfully run. Eventually one of cycuc's team members had updated the system for it to successfully run in console. For the most part, this system provides functionality as described in the assignment specifications. For example, the formatting of both the date and power / energy is not in the same as the sample output given.


Below is a sample run of team cycuc’s system:




For the most part, this system provides functionality as described in the assignment specifications. For example, the formatting of both the date and power / energy is not in the same as the sample output given.

> current-power Ilima-A
Ilima-A's power as of 2011-11-07 13:48:56 was 2.3 kW.
> daily-energy Mokihana 2011-11-05
Mokihana's energy consumption for 2011-11-05 was: 89 kWh.
> energy-since Lehua-E 2011-11-01
Total energy consumption by Lehua-E from 2011-11-01 00:00:00 to 2011-11-09 12:34:45 is: 345.2 kWh
> rank-towers 2011-11-01 2011-11-09
For the interval 2011-11-01 to 2011-11-09, energy consumption by tower was:
Mokihana 345 kWh
Ilima 389 kWh
Lehua 401 kWh
Lokelani 423 kWh

This may be an issue for some people depending on how they plan to process the data given. Reporting the data given in units such as kilowatt may be more desired. In the case of the rank-towers command, no units appear next to the output given which may confuse those not familiar with the system. Also, it appears that for the commands daily-energy and energy-since reports the wrong units with respect to the data given. From personal experience with the getData() method, the data returned by this method must be converted correctly to M Wh. In this case, 549 kWh should be 0.549 M Wh.

For example, the formatting under the current system is as follows:





Some of the commands do not successfully return data at all. Essentially the system attempts to implement the four commands listed in its help menu. The exact usefulness of this system is debatable as we deem this version of cycuc’s system not ready for distribution.



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

To answer this question, you should begin by carefully reviewing the project site associated the system. Does the home page provide a clear understanding of what the system is supposed to accomplished, perhaps accompanied by sample input and output? Is there a User Guide wiki page that provides details on how to download, install, and execute the system as a user? Is there a downloadable distribution that provides an executable jar file, so that users do not have to compile and build the system in order to use it? Does the distribution contain a version number so that users can easily keep track of what system they are using as it evolves over time?


In addition to containing the files for hale-aloha-cli-cycuc, the project site provides a very general idea of what the project is and does. The home page has a brief description of the system and a picture that presumably provides an explanation for the group name. This does give viewers an idea of what the system does, but not a very clear concept. There is no User Guide page; instead is a page titled “PageName” that contains most of the information that the User Guide should. The exception though is how to execute the system, which is not covered. The distribution file in the Downloads section does include a working version of the system along with an executable .jar file. The version number is included in the distribution folder name, allowing users and developers to distinguish between different versions. These version numbers include the timestamp corresponding to the time at which the distribution was created, thus letting users and developers compare versions chronologically. The numbers that actually indicate major and minor versions appear to have remained at 1.0 since the first downloads became available.


Next, you will want to exercise the system under both valid and invalid inputs, and see if the system responds in a useful way under both conditions. You must document what inputs you provided to the system, how the system responded to the inputs you provided, and then come to a conclusion regarding the "usefulness" of the system.

The tests of the system are shown below:

Valid input:



Invalid input:




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

To answer this question, you should first carefully review the Developer's Guide wiki page to see if it provides clear and comprehensive instructions on how to build the system from sources. The Developer's Guide wiki page should also indicate whatever quality assurance standards are being followed for this project (automated, or "manual" (testing)), and how a new developer can ensure that any code they might write adheres to these standards. If there are coding standards, are these documented? If there is a development process that is being followed, such as Issue Driven Project Management, does the Developer's Guide explain the way that the developers for this project have implemented this process? If the system is under Continuous Integration, does the Developer's Guide provide a link to the CI server associated with this project? Finally, does the developer's guide explain how to generate JavaDoc documentation?



The Developer's Guide wiki page on the cycuc project site provides clear instructions on how to build the system in Ant. Also, the guide includes information on the automated quality assurance tools used on the project. However, specific information about those tools is not given but developers are informed that the verify task will run all of the automated quality assurance tools. A link to the formatting guidelines is provided to document the stylistic rules that the code is to follow. The Developer's Guide does not mention Issue Driven Project Management or Continuous Integration. Similarly, instructions on how to generate JavaDoc documentation are not available, though the documentation does appear to come with the project in /doc.



Next, check out the sources from SVN (read only), and see if you can generate the JavaDoc documentation. If it can be generated, review all of the JavaDoc pages to see if they are well-written and informative. Do the JavaDocs provide a good understanding of the system's architecture and how individual components are structured? Do the names of components (packages, classes, methods, fields) clearly indicate their underlying purpose? Is the system designed to support information hiding?



JavaDoc documentation, as mentioned above, comes with the project in /doc. However, developers may still generate JavaDoc files through Ant or Eclipse. The JavaDoc documentation itself tends to be well-written, though there are some questionable points and the description is somewhat sparse. Several methods lack descriptions in their JavaDoc documentation. There are a few contradictions within the documentation, as in CurrentPower.java where the description for the printResults method (line 28) indicates that the text printed is based on days[0] while the parameter tag for days (line 31) states that days is ignored. However, the JavaDoc documentation did show the organization of the system, and the names of the various components were well matched with their actual purposes. The system does appear to have been designed to implement information hiding, with the Command interface serving as an example.



Next, see if you can build the system from sources without errors. See if you can generate coverage information regarding the system. Next, review the test case source code to see how the current developers are assuring the correctness of the functionality of the system. By combining information from the coverage tool with review of the testing source code, you should come to a conclusion about how well the current set of test cases can prevent a new developer from making enhancements that break pre-existing code.



The cycuc system builds without errors in most cases. A timeout while attempting to access the server will cause the entire build process to stop, which accounts for the instances in which the build fails. Aside from timeouts, the system builds properly.

The data that Jacoco provides concerning test coverage does induce some slight concerns about the validity of the testing. The halealohacli package has no testing at all. Testing on the halealohacli.processor package covers 67% of the code and 58% of the possible branches. For halealohacli.command, 94% of the code was executed in testing, while 59% of the branches were taken. (These values seem to vary upon repeated testing; this may be due to the aforementioned timeouts.) These low values for branch coverage in particular may stem from a lack of testing for invalid input. As a result, none of the exceptions are checked. The tests indicate that parts of the system work for a particular input; however, as there is only one test per test class (with the exception of TestProcessor) it is difficult to be certain that the system does behave correctly. Thus, the existing testing will not necessarily stop new developers from breaking the system; the testing ensures that developers cannot treat valid input incorrectly, but does nothing to stop invalid input from causing problems.



Now read through the source code, and check to see if coding standards are followed and if the code is commented appropriately. Is the code easy to understand, and is there neither too much nor too little commenting?



With regard to coding standards, there exist several minor deviations from the standards that do not affect the readability of the code. The amount of comments varies: at times, there is a comment explaining every line of code, while at other points there are entire blocks of code without any documentation. The deviations from the coding standards are provided below:

EJS-07: Include white space.
There is a lack of whitespace in the test methods of TestRankTowers, TestDailyEnergy, and TestCurrentPower.

EJS-13: Capitalize only the first letter in acronyms.
HaleAlohaClientUI class capitalizes “UI” instead of only capitalizing the first letter. Admittedly, “HaleAlohaClientUi” might have been confusing to read.

EJS-29: Qualify field variables with “this” to distinguish them from local variables
In HaleAlohaClientUI:
HaleAlohaClientUI:
prompt (line 66)
isFinished:
finished (line 27)
promptForOperation:
scanner (line 130)
In Operation:
getString:
string (line 35)
In CurrentPower:
getPowerConsumed:
powerConsumed (line 24)
In DailyEnergy:
printResults:
energy (line 44)
In TestProcessor:
testGetSource:
processor (lines 37, 47, 59, 60, 75, 80, 81)

EJS-30: When a constructor or “set” method assigns a parameter to a field, give that parameter the same name as the field.
In Processor:
setSource (line 135)
setTimestamp (line 81)
Note though that in both of these cases the methods are not actually setting the field to the parameter value.

EJS-31: Use uppercase letters for each word and separate each pair of words with an underscore when naming constants.
In HaleAlohaClientUI:
prompt (line 34)
In Operation:
quit (line 10)
help (line 12)
currentPower (line 14)
dailyEnergy (line 16)
energySince (line 18)
rankTowers (line 20)

EJS-33: Keep comments and code in sync.
In HaleAlohaClientUI:
“When we have the processor class implemented...” (lines 38-39)
The Processor class is already implemented as of this writing.

EJS-35: Use documentation comments to describe the programming interface.
In HaleAlohaClientUI:
JavaDoc comments were used repeatedly where single-line comments would have been preferable.

EJS-53: Provide a summary description for each class, interface, field, and method.
In HaleAlohaClientUI:
isFinished (line 26)
In DailyEnergy:
getEnergy (line 48)
In EnergySince:
getEnergy (line 49)
In RankTowers:
rankTow (line 56)
In Processor:
getTimestamp (line 179)
getBeginningTimestamp (line 187)
getEndTimestamp (line 195)

ICS-SE-Java-6: Format JavaDoc summary lines correctly.
In TestDailyEnergy:
test (line 22)
The first “sentence” in the JavaDoc documentation is “1.” This does not adequately describe the method.

Overall though, the code is readable; admittedly, the person testing the code had already implemented the project for a separate group and thus might be familiar with the objectives of the code, which would affect the results and opinions of the tester.



Next, check the Issues page associated with this project. Is it clear what parts of the system were worked on by each developer? If an external developer had a question regarding a certain part of the system or a certain aspect of its behavior, could the Issues page be used to determine which developer would be the best person to ask? Does the current system appear to result from approximately equal input from all of the developers, or did some developers appear to do much more than other developers?



Looking through the Issues page associated with this project, it is clear what parts of the system were worked on by each developer. This team utilized a variety of status options available to better inform an external developer what worked and what didn’t work with respect to project progression. In some cases, clarification in the form of comments show the decision making process this team used when dealing with issues. Since each issue described clearly explains what the task was, it should be easy for an external developer to determine which developer would be the best person to collaborate with. In terms of work input from all of the developers, it appears that some team members did more than others.



Now check the CI server associated with this project. Apart from Nov 22-24 when there were known outages, did any build failures get corrected promptly? Was the system worked on in a consistent fashion? Were at least 9 out of 10 commits associated with an appropriate Issue?



Turning to the CI server associated with this project, it appears all build failures were corrected promptly with a maximum latency of roughly 30 minutes. Also, looking through each successful build, this team showed that they were working on this project in a consistent fashion where at least 9 out of 10 commits associated with an appropriate Issue.

Hearts of Darkness: A Programmer's Apocalypse

Group work. For the most part working with other people can be an unpleasant experience. Often times one finds themselves carrying the group for whatever reason, but in this instance I can gladly say this wasn't the case. After getting our feet wet with the WattDepot API, my peers and I were split into groups to apply everything we've learned so far in software engineering (Ant, Google Project Hosting, Jenkins, etc..) to develop and maintain a small application that will display various energy usage in the Hale Aloha residence halls.

Taken from the help command in our program, the following were to be implemented:

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)

With three people in the group, we decided to split up the tasks as follows:

Input Parsing - To validate user input and make sure that it makes sense.
Program Processes - Takes user input and retrieves information from the WattDepot servers.
User Interface - Provides a simple command-line interface that allows for user interaction.

The assignment of tasks was deliberate as to cater to our strengths and weaknesses. In this case, only one of us completed all WattDepot katas in the previous class assignment.

Initially, there were some things to get used like creating an issue in Google Project Hosting that describes the task at hand. For example, the tasks above were broken down into smaller subtasks that are intended to be completed in 1 - 2 days. As detailed in the Issue Driven Project Management lecture, we tried to adhere to some rules that would lead to a successfully managed managed project:

Divide the work into tasks.
No task takes longer than 2 days.
Each task is specified by an issue.
Each issue has a single owner.
At all times, every person has an open task that they are responsible for completing.
Every commit specifies an issues in its log comment.

However, there were some issues with respect to these goals. Because of the way we subdivided the tasks, there were times in the project where I was blocked from completing my task. Working with the user interface, I described to a member handling the parsing portion of the program how I intend to send information inputted from the user to their package of commands. From there, he would parse user input and check the validity before passing it on to our team member handling the processing of data. Finally, the output returned by the WattDepot API would trickle back to me where it is finally outputted to the screen. Although we could have broken up the Processes package into smaller tasks, one group member felt confident that he would be able to handle the four commands without issue. This same group member happened to be the most talented of our group with respect to Java. Although we expressed an interest to create our own JUnit tests for each package, he was able to churn out the JUnit tests for each command in the processor package like he had been doing it all his life. This was not in vain, however, because when it came time to put everything together, I often had to go back into each test and verify that everything was working properly since we had some cross-platform issues regarding Ant and the verify task.

Instead of meeting regularly, we decided on meeting regularly online once a week over Google Docs and using the document feature to take notes that everyone could see. This worked out pretty well since this sort of acted as a virtual white board for us to hash out ideas. We also met twice a week before class to clarify anything that needed to be addressed, and we also used standard email as a message thread between the three of us to collaborate asynchronously. This allowed our group to be up-to-date on the issues going on with the project and thus actually worked out pretty well. When someone would finish a task, the issue of "What now?" would often come up and we were able to quickly find things to work on despite being trivial in nature. For example, while two people were finishing up with the Java portion of the project, another would be administering the Google Project Hosting site with regard to wiki pages and evaluating the issues and updates page to see if it met the class standards. This kind of work ethnic employed by our group ensured that we were always on top of things despite the rocky start with getting used to the whole process of project management.

In terms of what we accomplished, we were able to implement all commands described above with little issue.

From our Google Project Hosting site:

https://code.google.com/p/hale-aloha-cli-teams/

This is a command line interface that allows users to view various information about power and energy consumption in the Hale Aloha residences on the campus of the University of Hawaii at Manoa. The current commands implemented are:

current-power: Finds the current power consumption for sources in the Hale Aloha residences.

daily-energy: Finds the energy consumption for a given source on a given day.

energy-since: Finds the energy consumption for a given source since a given date.

rank-towers: Sorts the Hale Aloha towers based on energy consumption.

Overall, I am satisfied with what we have produced. It would have been interesting to see how far we could have taken this project by extending it using Java Reflection, but we wanted to make sure we had a solid product before trying something new.