Enhancing the BackR

In my last posts, I had covered some concepts about Issue Project Management and WattDepot. While in my last project with two fellow classmates we created a Wattdepot system called Hale-Aloha-cli-Bking, now it was our turn to enhance, not our system, but another system created by a different group.
That group is the "BackR", which I had previously made a technical review about its system. Just to mention the quality of the "BackR" system, I would say it looks quite comprehensive but at the same time very tedious to understand since it uses a wide range of advance functionality (such as Reflection). I had a hard time trying to figure out the overall functionality, since it is more complex than I thought. However, after going through all the code (which took me around an 1 hour), it was pretty simple to implement the three modules, described as follow:


(1)  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.
-------------------------------------------------------------------------------------------------------------
(2) 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.
-------------------------------------------------------------------------------------------------------------
(3) 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.
-------------------------------------------------------------------------------------------------------------

After doing a preview of the three modules with my group, we thought it would be simple to implement all those three modules. Yes, it would be simple to enhance in our system, but not in a another group's one. However, having successfully passed the Three Prime Directives (reviewed in my last post), we had a well-code written developer guide for us to enhance the system.

As mentioned by my fellow classmate Sean Chung in his post, he explained how the system strictly enforce the use of a specific number of arguments,  giving us no choice for optional arguments. Sean fixed that, but I ran into another problem. How do we then keep the baseline for each tower after we call the method "set-baseline"? I couldn't save it in the Processor class since every time a user enter a new command, then it would create a new Processor object. I couldn't save it also in the MonitorGoal class, since an instance of every module is created after each command call. So I decided to save in the Main HaleAloha program. I had to use some static fields and methods; otherwise it will have the same problem as mentioned above since I would have to create a new instance of the main class after every "monitor-goal" command call.

It would be great that the previous group would have implemented a database to save the baseline, but I do not really blame them. It was an unexpected issue I had to deal with, in which most of the programmers out there usually experience. Therefore, this debugging experience taught me that how important is to implement something that will be useful to enhance and maintenance the system in the future. Also it taught me how important is to stick to the Three Prime Directives for the best functionality of the software.

Spotlight: the BackR. A Technical Review

Last week I mentioned that I was working on some kind of project with two fellow classmates. So now, we took the role of a technical reviewer. We are now to review another group's project which implemented the system as we did: the HaleAloha-cli. Just in case if someone did not read my previous post, the HaleAloha-cli is a type of command line interface (CLI) which retrieve energy data from some dorms at the University of Hawaii at Manoa  using the Wattdepot Server. I dedicated a post about energy in Hawaii which introduce Wattdepot at the end. Also a post about my experience through some katas in order to learn more about the Wattdepot system using Java. Wattdepot is basically a open-source software dedicated to collect and storing energy data using electricity meters.

The project name I am reviewing is called the hale-aloha-cli-backr (they used "backr" because the three members sat at the back row of the classroom. Ha!), and for more information about the that project, the project page can be found here. The project, as mine also, is worked on using the idea of Issue Driven Project Management (IDPM). This allows the members of the group to break down the project into small tasks called "issues" which has to be update constantly until it is done. Their Jenkins website project can be found here. I think I did not mention about Jenkins in my last post, but it is basically a Continuous Integration (CI) which monitors the repository of a system or application being developed. CI standards propose that all issues must be updated constantly until the issue is done. This will make the developer to constantly work on the project.

While reviewing the system, I will be using the Three Prime Directives guideline.
Prime Directive # 1: The system accomplishes an useful task.
Prime Directive # 2:The system can successfully be installed and used by a new user.
Prime Directive # 3:The system can successfully be understood and enhanced by a new developer.
It is the most standard and frequently used open - source production guideline to review the quality of the system/application. For more information, please refer to my very first blog about the Three Prime Directives, in which I reviewed an open - source application called the "Sweet Home 3D".

So without any further due, lets begin the technical review.

Prime Directive # 1: The system accomplishes an useful task.
To review the first Prime Directive I just download the system, and run the commands. It was fairly straightforward to download the system and use it if you go through the UserGuide wiki page. Just to point out a tiny thing is that it is not necessary to compile the source code. The jar file was there and it was ready to be used. So I don't think the Ant step in the UserGuide should be there, maybe it should be in the DeveleporGuide.

As seen above, all 5 commands/modules were fully functional and were implemented successfully. There were some errors when running with some other towers or lounge which gives me an error saying that the "date is too back in the past". I tried 2011-11-11 and still it gave me that error. Maybe it is due to the Wattdepot server which was shutdown last week and might had produce some kind of lost of data. However, the system did accomplished successfully a task. So Prime Directive # 1 PASSED!


Prime Directive # 2:The system can successfully be installed and used by a new user. 
This time, I inspect the overall hale-aloha-cli-backr's homepage. The main home page clearly explained what the system does (with some nice graphics, a plus). There is a download distribution in .zip file which contains the jar file ready to use without any compilation of the source code. The distribution also does contain a version number (v1 as 12/1/2011) which can be changed when another developer update the system.

The UserGuide wiki page contains precise information about the system. The UserGuide is clearly explained for a new user (maybe someone not familiar with Java or Ant) to download the current distribution and use the jar file. However, as I mentioned above, maybe the Ant step in the UserGuide has to be deleted since the system should be compiled and ready to use for the new user.

Now, I will be testing invalid inputs and check if the program catches all the errors. Below shows a series of incorrect input with their output warnings.

Good! the system caught all the errors I had input. There is just one thing that I think commands should ignore upper-cases. Who knows, maybe someone prefers upper-cases rather than lower-cases, or maybe there was a typo. Nobody is perfect! Ha! And for this particular system it does not ignore upper-cases except for "quit". It is not a big issue, and maybe it was their own idea and design to go with that. Prime Directive # 2 PASSED!


Prime Directive # 3:The system can successfully be understood and enhanced by a new developer.

Now, I will inspect the system as a developer who wants to enhance the system. First I checked the DeveloperGuide wiki page. Easy to follow, but only for someone who knows about Ant and Java. SVN is mentioned but it is not clearly explained what it is. However, it does explain how to run the QA tools and generate Javadocs at the same time. It does also explain the overall structure of the system, explaining what classes are implemented and provide some guidelines on how to enhance the system. 

After that, I went to check the generated Javadoc documentation of the program. It is way clearer than my group system's Javadoc documentation. It is clearly and nicely explained. Naming convention to the classes, variables, etc are very clear and provide a good sense on what they actually do. Overall good job on this part. 

To check the coverage of the program, I ran the Jacoco tool. It covers 82% for overall instructions and 72% for branches. Not bad, since 100% does not imply that it is a perfect system. Then I checked each test cases and it seems that most of them have fully coverage on the code. Each test case is associated to one command/module, so there should not be any problem when enhancement is done by a new developer. Developer will just need to add a new command in the command package and create a new test case for that particular new class command class created. 

Checking through the source code, I will say it is fairly easy to read and follow. Comments were everywhere that allow developer to better understand what the code is doing. Overall, good job on this part also. 

Now checking the issue page on the home page website, there were lots of issues that were taken care of. The issue page shows what task or problem a developer was working on. Therefore, an external developer would know who to contact to ask some question regarding some part of the system. Issues were also clearly stated on what it was about, and it seems that the amount of work were equally distributed since the amount of issues are almost the same. 

Now lastly, checking the CI server (Jenkins) it seems that developers were constantly working on it since there were updates every day, until the Wattdepot server went down. There were three failures in total (no counting when the outages occurred) but it was corrected immediately. Finally I would say most of the commits were associated with at least one issue.   Prime Directive # 3 PASSED!


Overall, the system looks good. As most of the other groups, some enhancement might be needed, but it is working really fine so far. I like also the way the guys implemented reflection to automatically store all the classes when running the system. A truly plus for them. Much more improvement could be done in the wiki pages for more information regarding tools for the developer that will need to use. Good job BackR!