A Technical Review

  The following is a technical review of a system that is identical to the one explained in detail in my previous blog post.  It is a command line interface for an energy database that provides some utility by providing different commands a user can issue to receive energy data. This review focuses on the Three Prime Directives of open source software development, you can think of these directives at the most general guideline and standard for open source software production. I have used Green and Red arrows to denote a success/flaw concerning the system. Any of the concepts talked about in the following Technical review can most likely be found in more detail in my past blog posts.  

So what is a technical review anyway ? Look at this :

Click Here

Just Kidding!
A technical review is a type of software review that involves a semi-structured process, usually including before hand preparation and a set of guidelines, including a focused area of examination of the system.  Having these attributes allows a reviewer, like myself, to more accurately review a system and give feedback which is helpful. So lets check out this system:

home page can be found here:

home page

To fully understand what we are testing please read the overview of the system on the home page.  It explains the system well.

The Continuous integration system can be found here:

CI

For those who dont know, a continuous integration system is a system that monitors the central repository of a system under development.  When the repository is changed the CI system runs a test to make sure that the change that has been made doesn't break the existing system.  this allows for early detection and correction of errors when working in development teams.

⬆  = GOOD JOB
⬇ = SOMETHING MISSING/WRONG

For this section I went to the home page, went to the downloads tab and downloaded the file. I then Unzipped the file and ran the jar file on the top level of the directory. after that I proceeded to use the system the following is what I found.

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

⬆I downloaded and ran the system without any troubles at all.
⬆I ran a few initial tests to see if the basic commands worked, the outputs were as follows:

> daily-energy Ilima 2011-11-28
Ilima's energy consumption for 2011-11-28 was: 611.7 kWh.
> current-power Lehua-A
Lehua-A 's power as of 2011-Nov-29 17:49:06 was  6008 kW
> energy-since Ilima 2011-11-27
Total energy consumption by Ilima from 2011-11-27 to 2011-11-29 is: 1558.3 kWh.
> rank-towers 2011-11-27 2011-11-28
For the interval 2011-11-27 to 2011-11-28, energy consumption by towers were:
Ilima      1182.6 kWh
Mokihana   1186.2 kWh
Lehua      1205.8 kWh
Lokelani   1387.2 kWh

⬆ No Problems with the functionality as far as I can tell. when entering incorrect information an appropriate message is sent to the user:

The command inputted was not recognized (Enter "help" to see a list of available commands)

There is a typo in the error message, but no big deal.

⬆ when inputting incorrect arguments into the commands I found that the daily-energy repeats the error message in this instance, but again not really a big deal.

> daily-energy Ilima 212-334-4324
The date 212-334-4324 is invalid (Enter "help" to see command usage)The date 212-334-4324 is invalid (Enter "help" to see command usage)

⬆ I also found that that the system is case dependent, which is not necessarily good or bad.
Overall the system works great as far as I can tell, friendly and informative error messages are given to the user if an error occurs, and I was unable to break the system. It absolutely accomplishes one useful task.

For this section I did basically the same thing as I did above, but I looked into the documentation a bit more including the Wikiʻs that can be found under the wiki tab. After getting the system running once again I tried to put in bad input to break it.

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

⬆When Inspecting the home site, the project home page is informative and well written.  the system is clearly described.

⬇At the time of inspection [Nov 29, 6 pm] there was No UserGuide present in the Google Projects website under the Wiki tab.

⬆There is a downloadable .zip file which contains the .jar file, very easy to download and run.
The download also has a version number, all is well with the distribution.

⬆As I did above here are some more example of exercising the system, All seems well:

> @#$%^&*(
The command inputted was not recognized (Enter "help" to see a list of available commands)
> 3412513 435345 345345
The command inputted was not recognized (Enter "help" to see a list of available commands)
> DaIlY-EneRgY IlimA 2011-11-27
The tower or lounge IlimA is invalid (Enter "help" to see available sources
> rank-touers 2011-11-27
The command inputted was not recognized (Enter "help" to see a list of available commands)
> current-power 2021-11-27
The tower or lounge 2021-11-27 is invalid (Enter "help" to see available sources
> current-power xxxx-xx-xx
The tower or lounge xxxx-xx-xx is invalid (Enter "help" to see available sources
> QITH
The command inputted was not recognized (Enter "help" to see a list of available commands)
> Help
Available commands for this system:

energy-since [tower | lounge] [date]:
 Returns the energy used since the date (yyyy-mm-dd) to now.

current-power [tower | lounge]:
 Returns the current power in kW for the associated tower or lou nge.

daily-energy [tower | lounge] [date]:
 Returns the energy in kWh used by the tower or lounge for the specified date (yyyy-mm-dd)

rank-towers [start] [end]:
 Returns a list in sorted order from least to most energy consumedbetween the [start] and [end] date (yyyy-mm-dd)

quit:
 Terminates execution

Note: Hale Aloha towers are Mokihana, Ilima, Lehua and Lokelani
Lounges are the tower names followed by a "-" followed by one of A, B, C, D, E. For example, Mokihana-A.

⬆Overall the system works well, cant break it, it works with good inputs VERY USEFUL !
⬇ You need a UserGuide.

The following involves a lot of concepts such as testing, coverage, documentation and code standards, SVN checkouts, and issue-driven project management. If you are unfamiliar with any of these concepts and wish to learn mor about them I would read my previous blog posts because they cover most of the main concepts addressed in the following section. These are also basic concepts in software development so there is a lot of information out there about them. 

Note: Jacoco is a coverage tool that this project used. It runs all of the test cases that are provided for the system and checks to see what percentage of the code was actually used, and which percentage was never used. remember coverage != good testing, good testing = good coverage. 

Issue-driven management:

blog post on Issue-driven management

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

DeveloperGuide:

⬆Indicate whatever quality assurance standards are being followed for this project
⬆How a new developer can ensure that any code they might write adheres to these  standards
⬆coding standards?
⬆Are these documented?
⬆Development process that is being followed aka Issue-driven?
⬆explains the way that the developers for this project have implemented this process?
⬆provide a link to the CI server associated with this project?
⬇ explain how to generate JavaDoc documentation?
   - system says verify will run java docs bust doesn't explicitly explain how to and then where to find the documentation for the system

⬆Project Checkout
⬆Generate JavaDocs
⬆Well Written/ Clear.
⬆Thorough documentation.

The documentation seems well organized and well written, there is no confusion of what each class/package does.  There seems to be no indication of information hiding. Overall good documentation.

⬆project builds
⬆Generate coverage

There is some missing coverage but upon inspection you can see that the missing code is all catch statements or error printouts.  It seems at though all of the non error related code is exercised in the test cases.

⬆The testing methodology appears to be very thorough.  Each teas class addresses a number of different inputs, correct and incorrect, for each class. Each class has an associated Test class to exercise it.  From this inspection it looks well done.  The amount and span of testing provided leads me to believe that if changes were made to the system that would cause the current system to fail, the test cases would catch it.

Code:

⬆coding standards are followed
⬆code is commented appropriately
easy to understand
- The code is commented appropriately and can be understood.  there are a few places in the code that I would like some explanation on, but it should be noted that I like a lot of documentation in the code I write and read. Overall the documentation of the code is good.

Issues:
⬆Is it clear what parts of the system were worked on by each developer?
⬆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
⬇ some developers appear to do much more than other developers

It seems to me like there is an unequal distribution of work within the team, which unfortunately happens, Mr. cshf...@gmail.com seems to have done a lot of the work, while the other team members contributed less.

CI server :
⬆corrected promptly
⬇worked on in a consistent fashion
⬇ commits associated with an appropriate Issue
A lot of builds were done today on the 29th, these most recent builds are not associated with issues. ⬆During what seems to be the core of the development phase all builds were associated with issues.


Overall we can see that this system is good, it is tested pretty well, it runs well, it is documented well except for a user guide. It passes the three prime directives.

Issue-Driven Project Managment

  In order to work in any sized development team the project at hand needs to be modularized in such a way that every developer on the team has a task to do.  Ideally, throughout the duration of development, each member of the team would always have a task to do, to avoid any wasted time.  It would also be ideal for each member to know which new task they can begin after completion of their current task.  In this way there is no confusion on the role of each developer in the team, this is more of less the goal behing issue-driven project management.  When managing a project utilizing an issue driven approach there are a few seemingly simple guidelines that I have used and found effective:

1. Divide up the work into tasks.
2. Make sure that each task is not too big, for the project I am currently involved in each task ideally takes no longer than 2 days to complete.  Large/lengthy tasks can lead to problems.
3. Each task is specified by an issue.  For examples of some issues please see These Issues
4. Each issue should have a single owner - as shown in the example above, this allows independent work.
5. At all time each developer should have a task they are working on.
6. Every commit or change to system should be associated with an issue and be documented accordingly.

  Although these guidelines seem more or less simple, actually implementing and upholding them in a real project can be challenging.  This became very clear to me as my team took on a simple project to develop a command line interface for a Wattdepot server. The home page along with a description of the functionality of the project can be found here : Halealoha-Cli-Hash
  In summary our team had to develop a small system that runs ont the command line that takes in a limited set of user commands, retrieve the appropriate information from the WattDepot servers, and returns the answer. the list of commands was as follows:

-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
Prints out this list

   As you can see, not too difficult, but despite the fact that the overall project was not too difficult we did run into some problems trying to use issue driven project management.  The first unseen difficulty was to divide up the work in such a way that no one persons work was dependent on the completion of another work.  This could end up stalling development especially when some group members work faster than others.  We were able to work out this problem, and it should be noted that having SHORT issues makes this problem a lot easier.  After our team got really going on the project we had few other difficulties.  We did have an unequal distribution of work in our team, but that is to be expected when dealing with a group of students with different work loads.  Our team was able to complete the project, and ahead of schedule, with the help of issue-driven management.  Overall I found using this type of project management to be simple and effective.  
If you want to check out the project you can find a download of it here: HaleAloha-Cli-Hash
Just check out the WIKI page for instruction on how to download and use the project.
Mahalo.

Jenkins

Jenkins is a continuous integration system, which for me means a system to check out, build and verify a project that I have created on google project hosting. My first Jenkins project can be found here:
Jenkins Green-Machine project
As you can see its been set up to monitor my Green-Machine Robocode project, It is configured to build the project using a jenkins.build.xml file which depends on a verify.build.xml file, which tests the project. Upon a build fail Jenkins will send a email to all of the project members, this is very advantageous because it allows early detection of any update that breaks there system.
I ran a test to see if Jenkins was working by breaking the project and I received this email.


------------------------------------------
[...truncated 77 lines...]
[javac] ^
[javac] :80: class, interface, or enum expected
[javac] public void onHitRobot(HitRobotEvent event) {
[javac] ^
[javac] :86: class, interface, or enum expected
[javac] gunTurnTo((int) getHeading() + (int) event.getBearing());
[javac] ^
[javac] :88: class, interface, or enum expected
[javac] setBulletColor(Color.RED);
[javac] ^
[javac] :89: class, interface, or enum expected
[javac] fire(Rules.MAX_BULLET_POWER);
[javac] ^
[javac] :90: class, interface, or enum expected
[javac] }
[javac] ^

...
..
.
As you can see the email actually indicated where the problem is(very cool). because i commented out teh class declaration for Green_machine I received a lot of errors.

WattDepot

WattDepot is an open source, RESTful web service that collects electricity data (such as current power utilization or cumulative power utilization) from meters and stores it in a database. The data can then be retrieved by other tools for visualization and analysis. It is designed to provide infrastructure for experimentation and development of "Smart Grid" applications."
From: WattDepot
  My last post was about energy and the unique energy situation we have here in Hawaii.  If you havent read over that post please feel free to do so here:
Lets Talk Energy
  WattDepot, as mentioned above, is a tool which allows us to collect and retrieve energy data from a database and use that data as we wish.  WattDepot is therefore a great tool for the analysis of energy data that can be used to monitor energy trends and usage and can be used educate, a good example of which is the kukui cup at the University of Hawaii at Manoa.
Kukui Cup
  To help us explore this new system we can apply the exercise of code katas ! Please refer to my older blog posts to learn about code Katas, and how I have used them in the past to explore new systems.  Befor we look at the Katas you can get a distribution of the WattDepot system here:
Distribution
Lets take a look at the Katas that I took on to help me understand how to write a WattDepot client.  I was able to finish them all, but they were not a walk in the park.

Kata 1: SourceListing

Implement a class called SourceListing, whose main() method accepts one argument (the URL of the WattDepot server) and which writes out the URL argument and a list of all sources defined on that server and their descriptions, sorted in alphabetical order by source name.  Use the System.out.format method to provide a nicely formatted list.  For example:

Server: http://server.wattdepot.org:8190/wattdepot/

Source                 Description

Bar                    Represents the energy consumed by the Bar building.

Baz                    Represents the energy consumed by the Baz floor of the Bar building.

Foo                    Energy generated by the Foo power plant.

Qux                    The energy meter associated with the Qux household.

Kata 2: SourceLatency

Implement a class called SourceLatency, whose main() method accepts one argument (the URL of the WattDepot server) and which writes out the URL argument and a list of all sources defined on that server and the number of seconds since data was received for that source, sorted in ascending order by this latency value.  If no data has every been received for that source, indicate that.  Use the System.out.format method to provide a nicely formatted list.  For example:

Server: http://server.wattdepot.org:8190/wattdepot/

Source                 Latency (in seconds, as of 12-Oct-2011 14:32:12)

Baz                    9

Bar                    10 

Foo                    14

Qux                    No data received.

Kata 3: SourceHierarchy

Implement a class called SourceHierarchy, whose main() method accepts one argument (the URL of the WattDepot server) and which writes out the URL argument and a hierarchical list of all sources defined on that server.  The hierarchy represents the source and subsource relationship between sources. For example:

Server: http://server.wattdepot.org:8190/wattdepot/

Source Hierarchy

Baz

  Bar

  Zob

    Zob-A

    Zob-B

Foo

Qux 

Thus, the source Baz has two subsources, Bar and Zob.  The source Zob has two subsources, Zob-A and Zob-B.  Foo and Qux have no subsources. The hierarchy is represented by two space indentation.

Kata 4: EnergyYesterday

Implement a class called EnergyYesterday, whose main() method accepts one argument (the URL of the WattDepot server) and which writes out the URL argument and a list of all sources defined on that server and the amount of energy in watt-hours consumed by that source during the previous day, sorted in ascending order by watt-hours of consumption.  If no energy has every been consumed by that source, indicate zero.  Use the System.out.format method to provide a nicely formatted list.  For example:

Server: http://server.wattdepot.org:8190/wattdepot/

Source                 Energy consumed in watt-hours (19-Oct-2011)

Baz                    932

Bar                    1025 

Foo                    1436

Qux                    2357

Kata 5: HighestRecordedPowerYesterday

Implement a class called HighestRecordedPowerYesterday, whose main() method accepts one argument (the URL of the WattDepot server) and which writes out the URL argument and a list of all sources defined on that server and the highest recorded power associated with that source during the previous day, sorted in ascending order by watts.  Also indicate the time when that power value was observed. If no power data is associated with that source, indicate that.  Use the System.out.format method to provide a nicely formatted list.  For example:

Server: http://server.wattdepot.org:8190/wattdepot/

Source                 Highest recorded power in watts (12-Oct-2011)

Baz                    10,034 10:30am

Bar                    10,456 2:45pm

Foo                    14,876 12:30pm

Qux                    23,578 4:15pm

This is a little tricky due to the presence of both virtual and non-virtual sources. For non-virtual sources, you could retrieve all of the sensor data and just iterate through to find the maximum power value. However, virtual sources represent an aggregate of non-virtual sources, so there is no sensor data associated with them directly, and it is unlikely that the sensor data timestamps for its constituent sources will be synchronized exactly.

One reasonable way to deal with this is to request the computed power at (say) 15 minute intervals for the entire day, which provides 96 data points per source whether it is virtual or non-virtual.

Kata 6: MondayAverageEnergy

Implement a class called MondayAverageEnergy, whose main() method accepts one argument (the URL of the WattDepot server) and which writes out the URL argument and a list of all sources defined on that server and the average energy consumed by that source during the previous two Mondays, sorted in ascending order by watt-hours.  Use the System.out.format method to provide a nicely formatted list.  For example:

Server: http://server.wattdepot.org:8190/wattdepot/

Source                 Average energy for last two Mondays in watt-hours (24-Oct-2011, 17-Oct-2011)

Baz                    10,034 

Bar                    10,456 

Foo                    14,876 

Qux                    23,578 

   Some of these Katas were more difficult than others, Kata 3, building the hierarchy caused me some hours of trouble, and learning how to manipulate Gregorian calendars also took me a while to become competent in.  Other than that there is a close relation between the last three Katas which made life a little easier.  I found implementing and utilizing a simple data structure to sort the sources as very useful.  Good Luck and Have Fun !!