In August, in a blog entitled, "Three Important Pixels", I've introduced three important rules under open source software engineering called the Three Prime Directives. I used these directives to evaluate a program called Pixelitor and so on to gain some experience using Java-based open source systems, and to gain an appreciation for the difficulties involved.
The Three Prime Directives are as followed:
- 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.
At the dawn of November sparks the introduction of WattDepot which is a system for collecting and storing data from electricity meters for smart grid research and experimentation. To better understand the aspects of WattDepot, I've undergone some software Katas to familiarize myself to the WattDepot API manipulating various energy data and displaying them in a given fashion.
Not found in my blog, but from personal experience came the introduction of Continuous Integration (CI). What may CI be? Well, tying all the aspects of what I've introduced to you is an important technique for high quality software development. CI implements continuous processes of applying quality control — small pieces of effort are applied frequently. Continuous integration improves the quality of software, and reduces the time taken to deliver it, by replacing the traditional practice of applying quality control after completing all development.
Finally this led to the hale-aloha-cli-backr project highlighted in the previous blog entry which also brought up the topic of Issue Driven Project Management (IDPM). IDPM breaks up a project worked on by several members and is divided into small tasks or "issues". Each person completes their issues and updates frequently to adhere to the CI standards.
Okay, so you're still here if you're reading this line. Let's go back to the review…
As stated before, I got the opportunity to review another hale-aloha-cli project created by another group of people. In this review, I will evaluating the software incorporating all the things learned throughout these past months and basing them off the first thing I introduced to you: The Three Prime Directives.
Review question 1: Does the system accomplish a useful task?
This project is just like the project I've worked on with my group, so it's basically our project envisioned by another group. I obtained a copy for this project and ran as many commands to view the feature set of this team's project. It seems that the group implemented all the feature commands:
- 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
- help
- Displays a menu of all possible commands.
With all of these commands, they provide useful tools for displaying various energy data gathered from the Hale Aloha towers at the University of Hawaii at Manoa.
Review question 2: Can an external user can successfully install and use the system?
Now lets get down to testing this project. The home page of this project describes briefly what the project is about. Also on the home page is a featured link to the user guide. The user guide written provides simple instructions to install the program and what available commands the program offers (as described in the help command). The downloads section of the project website provides a distribution with the current version number of the project. Unzipping this file outputs the source and an executable jar file.
After an extensive testing continuing from the first prime derivative, I've tested this program thoroughly and noted these errors and findings:
- Program crashes when entering any number of space characters without any characters entered.
- If a correct command is called without any parameters, it gives the same help information.
- The help command with parameters still gives help and doesn't catch error.
- The output of the help dialog needs more spacing between information to be easier to read.
- Some commands catches invalid date format, but needs to be more clear on the specific error.
- rank-towers does not have energy rating units.
- energy-since without a tower goes through but brings up a generic error message, needs to be more specific.
- Calling daily-energy without a tower or lounge but having the date parameter in a correct format gives an error specifying that there was an error accessing the blank tower.
- Calling rank-towers with a future date in the end parameter crashes the program.
- Calling rank-towers with the end date lower than the start date gives the correct error.
- Given a date far in the past gives a generic error that should be more specific.
Review question 3: Can an external developer successfully understand and enhance the system?
For this part, we'll take the shoes of a developer. On the website for the project, it also provides a developer guide along the user guide. It provides a short sentence on how to build the system and lists all the types of automated quality assurance it runs. Though it doesn't mention if there are any manual testing done. Provided is a coding standard used for the project and a link to it as a plugin of the Eclipse IDE. The remainder of the guide describes the packages of the program and their functionality. There is no mention if this project is under continuous integration, no descriptions on how the project was implemented and contains no explanation on how to generate javadoc.
After examining the website, I move on to checking out a copy of the project from the repository. I was able to find an ant build in the project that generates javadoc. The javadoc of the system seemed clear and simple, but maybe a bit short. However, the names of the components in the project are clear and provides a sense on what they do. Within the processor class are hard coded command class, so there is some information hiding since one could update the processor class to add in additional functionality.
Upon building the system, there we're no errors. Generating test coverage from the jacoco ant build provided an overall 85% coverage for instructions and 65% coverage for branches. The manual test cases in the program tests one java source according to the name. If any additional enhancements to the project should occur, it would not disturb these test files since enhancements should come in the command package as specified by the developer guide on the project's website.
Overall after reading through the source code, I would say that it was fairly easy to read, but the comments in the code was on the low side. Some additional comments would be helpful to explain some algorithms such as get the user's input date and parsing it.
Back to the website to do more analysis. This project was developed under Issue Driven Project Management, so there were a see of issues assigned to each member who completed that assigned task. The issues page clearly shows on which member worked on what and would give a clear sense on who to question if a new developer works on this project. The system does show that one developer did more work than the fellow members but most of the issues this user committed were testing issues.
Even though it was not specified in the developer guide, this project was ran under continuous integration. I was given the link to the CI build site and did some analysis on it. Failed project builds seemed to be corrected promptly, though there was a lengthly correction for build #4 - #7 which took 11 hours and 52 minutes to correct. The project did seem to be worked on consistently with build every day or two though not all builds were associated with an issue. Here's a breakdown of the builds with no issues:
- #1-14 no issues associated with upload.
- #16-19 no issues associated with upload.
- #24 no issues associated with upload. Started by user.
- #29 no issues associated with upload.
- #32-35 no issues associated with upload. Started by SCM change.
- #43 no issues associated with upload.
- #47 no issues associated with upload.
- #49 no issues associated with upload.
- #51 no issues associated with upload. Started by SCM change.
- #53 no issues associated with upload.
- #55 no issues associated with upload.
- #56 no issues associated with upload.
- #57 no build.
- #58 no issues associated with upload.
Overall, the project seemed easy to read and with some time someone would understand it. Since much of the program to call the command package from the run class is hardcoded into the processor class, an external developer would have some ease on adding more elements to this system. All the developer needs to do is hard code the new command class into the processor, produce a working new command class and add tin the description into the help command. It will be a simple task, but since the developer will need to update 2 classes and provide a new one, it will also be a lengthy task.
Links:
Three Prime Directives (Blog Entry) : http://elmarcarillo.blogspot.com/2011/08/three-important-pixels.html
Robocode : http://robocode.sourceforge.net/
Robocode (Blog Entry) : http://elmarcarillo.blogspot.com/2011/09/kode-cut-row-bow-code.html
Apache ANT : http://ant.apache.org/
ANT (Blog Entry) : http://elmarcarillo.blogspot.com/2011/09/awesomely-nifty-thing.html
CheckStyle : http://checkstyle.sourceforge.net/
PMD : http://pmd.sourceforge.net/
FindBugs : http://findbugs.sourceforge.net/
WattDepot (Blog Entry) : http://elmarcarillo.blogspot.com/2011/11/shopping-for-electricity-at-wattdepot.html
hale-aloha-cli-backr (Blog Entry) : http://elmarcarillo.blogspot.com/2011/11/command-line-in-back-row.html
No comments:
Post a Comment