Both the hale-aloha-cli-chair and hale-aloha-cli-hash projects set out to accomplish the same goal: a Java based implementation of a Command Line Interface which provides its users a functional way of interacting with WattDepot energy data from the Hale Aloha student residence towers on the campus of the University of Hawaii at Manoa. In this implementation, both our teams set out to design an open source system which has six commands built-in: help, quit, current-power, daily-energy, energy-since and rank-towers. For a more in depth description of the commands' functionality, I present to you the project page for hale-aloha-cli-chair.
If you'll recall from my first blog entry, the all-encompassing goal of open source software boils down to a useful application for users and a higher level of effectiveness in allowing developers from anywhere contribute with relative ease. Thus, I reiterate here once again, for your convenience, the three Prime Directives of open source software engineering:
Prime Directive #1: The system successfully accomplishes a useful task.
Prime Directive #2: An external user can successfully install and use the system.
Prime Directive #3: An external developer can successfully understand and enhance the system.
However, whereas the previous review of the open source project aTune was a mere glance at a well-established application, I am now in an unique position where I am able to test and review an early version of hale-aloha-cli-hash to which I will have access to all of the quality assurance tools the hash team was using as well as a general insight into their goals as I analyze their source code and architecture in depth.
I would be remiss, however, if I didn't do my due diligence and lay down a better picture of the general approach to the project that both the chair and hash teams took towards the Command Line Interface implementation. To be brief, the project consists of energy usage by students in the Hale Aloha towers being recorded by sensors which communicate its data to a WattDepot database which allows the Command Line Interfaces to retrieve relevant energy data to display to the user of the CLI.
 |
| OK, you caught me, those are not WattDepot servers, but look how happy that user is with the CLI! |
To learn a bit more about how WattDepot can be interacted with, see my previous blog entry regarding my initial experience with WattDepot. From a user's perspective, this is a more than sufficient information to begin using the CLI. However, from a developer's standpoint, there are a few more objectives in the CLI implementation. First of all, both of these CLI project are managed by an Issue Driven Project Management system and are under Continuous Integration.
For your experienced developer, these concepts may not be a shock at all, but for those of you who are new to software development or are simply interested in educating yourselves, both of these processes are tools which aid a development team in achieving efficient collaboration. Issue Driven Project Management, or IDPM, is a means of managing a project by creating simple, uncomplicated issues which can be resolved in a short span of time. What this allows a project team to do is to create a large quantity of small tasks for its team members to draw upon so that they will always have something to work on at their pace. Since the issues are quickly resolved, IDPM also requires that the team members put their heads together frequently to generate more issues so that their resources (read: developers) are never idle. In supplementing IDPM, there are a number of automated quality assurance tools that are required for successful development of the CLIs as well. These assurance tools allow for a concept called continuous integration.
When multiple developers are working on a project concurrently, there is bound to be an integration issue. Even though developers may be working on separate issues, they may end up modifying something similar and conflict with one another's work. What continuous integration does is not to prevent these conflicts from happening but to make certain that the conflicts can be quickly resolved. If developers are committing their changes to the shared repository with a higher frequency, the amount of modification to overcome when a conflict occurs is going to be smaller. This means that in order for continuous integration to work, changes made by a developer must automatically be checked for errors by quality assurance tools and each developer must make small but frequent commits to the repository.
Armed now with this barrage of conceptual knowledge, I invite you now to cruise alongside me as I walk through my technical review of hale-aloha-cli-chair's
Prime Directive #1: The system successfully accomplishes a useful task.
To answer this question, I first went to the hale-aloha-cli-hash project page where I was able to download the latest distribution of the project.
I first ran through the system using correct input values:
E:\Downloads>java -jar hale-aloha-cli-hash.jar
Connected successfully to: http://server.wattdepot.org:8190/wattdepot/
>
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 (yy
yy-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 [s
tart] 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.
>
current-power Ilima
Ilima's power as of 2011-12-01 was 27.439735792375984 kW
>
daily-energy Ilima 2011-11-30
Ilima's energy consumption for 2011-11-30 was: 664.6056753929341 kWh
>
energy-since Ilima 2011-11-25
Total energy consumed by Ilima from 2011-11-25 to 2011-12-01 is: 3951.9046231694
37 kWh
>
rank-towers 2011-11-25 2011-11-30
Enter dates as YYYY-MM-DD
Older data may not be valid.
Command was not processed, please check for correct arguments
>
rank-towers 2011-11-25 2011-11-30
Source For the interval 2011-11-25, 2011-11-30 energy consumption by tower was:
Mokihana-06-telco 126 kWh
Lokelani-08-telco 131 kWh
... (truncated for the blog entry's sake)
Ilima 3601 kWh
Lokelani 4172 kWh
>
quit
Of the six commands the CLI is supposed to have implemented:
> help: provided a helpful message explaining the usage.
>current-power: implemented and functional.
>daily-energy: implemented and functional.
>energy-since: implemented and functional.
> rank-towers: implemented but for gave errors at times even with correct input. Also ranks towers AND lounges instead of just towers, but this is more of a design choice than a problem.
>quit: exited the system cleanly.
All of the intended functionality of the project were implemented and working. Although the rank-towers command did not always properly execute, the system is still overall useful and it is fair to say that, although it is not without bugs/flaws, hale-aloha-cli-hash does indeed accomplish a useful task.
Prime Directive #2: An external user cans uccessfully install and use the system.
In order for the project to allow an external user to successfully install and use the system, there ought to be some features about both the project itself and the project homepage which provides guidance for the average user who may not know much about software development. There were several questions I asked myself in order to determine if the hash team was successful in conveying this user-friendliness.
> The project homepage provides an overview of the purpose of the application and briefly lists the available commands.
> There is a User Guide wiki page featured on the project homepage which describes how to download, install and execute the system. The wiki also lists the available commands again, and a more detailed description of each command.
> The downloadable distribution includes an executable jar (the execution of which was seen up above) which means the user doesn't have to know how to compile and build the system in order to use it.
> The system version number is clearly attached to the project distribution and users can easily use this to keep track of the which evolution of the system they are using.
In addition to the valid inputs above, I also tested the system with invalid inputs.
E:\Downloads>java -jar hale-aloha-cli-hash.jar
Connected successfully to: http://server.wattdepot.org:8190/wattdepot/
>
hello world
Invalid Command
>
HELP
Invalid Command
>
current-power
Invalid Number of Inputs
>
current-power foo
Command was not processed, please check for correct arguments
>
current-power 1 2
Invalid Number of Inputs
>
daily-energy foo bar
Error occured while running daily-energy.
Command was not processed, please check for correct arguments
>
daily-energy Ilima foo
Error occured while running daily-energy.
Command was not processed, please check for correct arguments
>
daily-energy Ilima 11-25-2011
Error occured while running daily-energy.
Command was not processed, please check for correct arguments
>
daily-energy Ilima 2012-11-25
Error occured while running daily-energy.
Command was not processed, please check for correct arguments
>
daily-energy Ilima 2011/11/25
Ilima's energy consumption for 2011/11/25 was: 548.7930279141283 kWh
>
current-power foo
Command was not processed, please check for correct arguments
>
rank-towers 2011-11-25 2011-13-25
Enter dates as YYYY-MM-DD
Older data may not be valid.
Command was not processed, please check for correct arguments
>
exit
Invalid Command
>
quit
Judging from the reasoning behind the invalid inputs, it was clear that in general, invalid inputs are broken up into three categories: unrecognized commands, incorrect number of arguments and everything else being simply errors occurring along with a helpful hint of what the user may have done wrong to illicit the error. Surprisingly, the CLI accepted my input of 2011/11/25 which is not necessarily a bad thing. The only reason this raises an eyebrow is because the hash team simply chose to disregard the the delimiters so an input such as 2011111225 (perhaps due to an inexperienced typist) will still be accepted and there may be some combination here which gives the incorrect date. However, here is the rundown of invalid inputs I tried:
> Completely invalid command was recognized as an invalid command.
> Upper case version of an available command was recognized as an invalid command.
> Invalid number of arguments (too many or too little) handled well and lets users know of the problem.
> Invalid arguments handled well but generally provides a general message as to why an error occurred (this is, again, more of a design choice than a problem).
> Strange delimiters for dates will be accepted as long as they are one character long.
Given that hale-aloha-cli-hash provided users a simple documentation of how to get up and running and continued to guide them throughout the usage of the CLI, I would say that the hash team did an admirable job of satisfying the second Prime Directive. As an external user of this application, I believe I would be capable of following the User Guide wiki and understand what the CLI is capable of from both the documentation and the built-in guidance that the application provides.
Prime Directive #3: An external developer can successfully understand and enhance the system.
Here is where the distinction between open source software and other software really shows up. This CLI implementation as well as our own does not only need to be useful to users and usable by users, but also expandable and modifiable by other developers. The goal of this project is to create a CLI with 4 built in commands for interacting with WattDepot energy data. However, it's also very important to note that, since WattDepot has so much other data available, it would be prudent to allow the CLI to be extensible with more commands. In determining whether the CLI created by the hash team does indeed allow for an external developer to easily enhance the system, I asked myself several questions to this end as well.
First, I investigated the project's homepage for some insight into the project and for hints on how to get started.
> A Developer's Guide wiki page was featured on the front page.
> The guide provided clear instructions on how to build the system from source files.
> The guide indicated the quality assurance standards being followed by the project.
> The guide provided some tips on how a developer might try to adhere to those quality assurance standards.
> The guide provided references to coding standards being followed.
> The guide mentions that the project is issue driven and explains how to partake in the project through creation of issues.
> The system is under Continuous Integration and the guide provides a link to the CI server associated with the project.
> The guide also explains how JavaDoc documentation can be easily generated.
Since the wiki page was very well done and provided a good insight into the development process, I felt confident with taking the next steps towards contributing to the project. I was able to check out the sources from SVN (recall my previous entry explaining the advantages of SVN) and generate the JavaDoc documentation for my perusal very easily. Regarding the JavaDocs themselves, I gained even further insight into the project.
> From viewing just the JavaDocs, I was able to gain a decent understanding of the system's architecture and the its components.
> For the most part, the naming scheme of the components were very intuitive and clearly indicated their underlying purpose with the exception of the existence of both a Node and Nod class. I was able to ascertain what a Node class probably does, but it seemed like the Nod class performed roughly the same duties. The name of the class being "Nod" was also a bit odd but this was just a small problem that I could certainly live with.
> The system is designed to support information hiding and uses the protected keyword so restrict access of certain methods to only those within the package. This is likely done to facilitate JUnit testing but also offers other advantages like being extensible.
After generating the JavaDocs, I was then able to build the system and generate test coverage information regarding the system using JaCoCo. Using this information and a review of the testing source code, I was able to determine that the existing set of the test cases were implemented rationally and does a good job of preventing new developers from making enhancements that can break the pre-existing code. In this analysis process, I was also able to gain a further insight into the hash team's reasoning behind certain design choices. In addition to reviewing the test case source code, I also reviewed the actual implementation source code as well. To this end, I found several more good qualities about the hash team's code.
> Java coding standards were followed.
> Comments were sprinkled throughout the code appropriately, giving new developers clues and explanations regarding existing code.
> The code is easy to understand and the comments were neither too sparse nor too overwhelming.
Since the project was under continuous integration, I also checked the CI server associated with the project to draw some conclusions about the consistency of the hash team's development process.
> Although there were build failures, indicating that a developer may have failed to verify the build prior to committing to the repository, the failures were always corrected promptly.
> The system was worked on in a consistent fashion, and commits from developers were done very frequently.
> Most of the commits made to the repository were associated with an appropriate issue, with the exception of a few quick fixes here and there.
Finally, although this does not really have a huge relevance (it is relevant, just not hugely so) on the third Prime Directive, I was curious to see how the system was contributed upon by its three individual developers. To this end, I reviewed the team's project page and analyzed the Issues page associated.
> It was evident which parts of the system were worked on by each developer.
> Based on the Issues page, it is apparently who I need to talk to if I had a question regarding a certain part of the system or its behavior.
> Even with just a simple glance at the Issues page, it becomes glaringly obvious that one particular developer contributed significantly less than the other two. Whereas developers BrysonYHori and mitchell.kupfer seemed to have implemented the majority, if not all of the system, developer macmillan.johnw contributed only two fixes to the project which, based on the Issues, were relatively minor and done in a single day's time frame.
Although hale-aloha-cli-hash is not without its flaws here, it is clear that a strong effort was made from the inception of this project to create a modular system which is open to external developers. From the project's homepage to the source code documentation and even the team's own striving for excellence in adhering to their coding standards, it is clear that this project is one that satisfies the third Prime Directive of open source software engineering. It is a shame that of the three developers on the team, there was an evident imbalance in contribution and effort but, once again, that does not factor into my analysis of the project's adherence to its goals at all.
Hale Aloha CLI CHAIR Project Page
Hale Aloha CLI hash Project Page
No comments:
Post a Comment