Uncharted Waters: Extending a Foreign System

Once again, it is time for team JCEV to tackle another CLI project for the Hale Aloha towers.  However, this time we did not design the system from scratch.  Instead, we took control of the hale-aloha-cli-kmj project that I previously reviewed and extended it by adding three new commands and updating the documentation.  So how did it turn out?  Well, as per usual I shall evaluate this new endeavor in the context of the three prime directives of open source software.

---

Prime Directive #1: Does the system accomplish a useful task?
To accomplish this prime directive, the system should fully implement the three commands specified.  The first command is set-baseline which records the energy used by a tower or lounge over a specified day in one hour periods and it should default to yesterday if no date is given.  In this case, the system successfully retrieves this data and stores the information in a Baseline object for later use in both cases.

set-baseline command with optional date argument.

set-baseline without the optional date argument.

The second command, monitor-power, should periodically retrieve the current power consumption of the given tower at the given interval.  The interval argument is optional and the interval between checks should be 10 seconds if not specified otherwise.  In addition, the command should stop execution when the user presses a key like enter.  This version of the system contains of the functionality as it periodically prints the results as expected.  The only small issues are that the command will not stop unless the enter button is pushed (i.e. the s and the a in the image below did not stop the command's execution) and that terminating execution causes an invalid command error.  These do not really affect the functionality though and hence this command is in working order.

The monitor-power command in action.

The third and final command is monitor-goal.  This command checks the current power consumption of the given tower or lounge and compares it to the baseline which must be set before running this command.  If the current power consumption has been reduced by the specified goal percentage or more, than it prints the goal has been met.  Otherwise, it indicates that the goal was not met.  The monitor-goal command does this periodically like the monitor-power command and should stop execution when the user presses a button like enter.  This implementation of monitor-goal suffers from the same problem as the monitor-power command as it requires the user to press enter to exit the command, but once the user presses enter, the command exits as expected.  As a result, all three commands work to accomplish a useful task and this system fulfills the first prime directive.

The monitor-goal command successfully executing after the baseline has been set.

---

Prime Directive #2: Can an external user successfully install and use the system?

I believe that this system fulfills this prime directive as well.  The original project was a little lacking in the user documentation due to a sparse home page and a few key errors in the UserGuide, but these have been fixed in the latest version.  The home page now sports many screen shots of example executions that users can reference and the new UserGuide removes some of the misleading instructions that afflicted the original guide (i.e. removed the unsupported sources that were previously listed).  The system is also very easy to install as there is a clearly labeled distribution to be downloaded on the website which contains an executable jar file that can be run without any compilation.  Consequently, I believe that the updated documentation should make this system easy to install and use, even for an external user.

---

Prime Directive #3: Can an external developer successfully understand and enhance the system?

Essentially, this entire exercise was a test of the third prime directive as my team (JCEV) had to adopt this code-base, understand how it worked, and extend it.  While we were successful in doing so, it was not an ideal experience as we had to figure out how to extend the existing system on our own.  The DevelopersGuide gave a general overview as to how the system worked, but the specifics of what changes were needed when adding a new command were nowhere to be found.  As a result, we had to skim over the code in the CommandParser class to figure out exactly what these changes were before we could add our new commands.  Of course, this was a pain and we decided to pardon any future developers from this experience by listing the required changes in the updated DevelopersGuide.  The DevelopersGuide was also updated with the coding standards that should be used in the project and some instructions detailing how to generate JavaDocs to further assist any future developers.  These changes should make it much easier for an external developer to successfully understand and enhance the hale-aloha-cli-kmj system and thus I think that it now fulfills the third and final prime directive.

---

Conclusion
Overall, this was an interesting experience in software engineering.  While we managed to implement all of the functionality and produced what I would consider high-quality software, it was not without its issues.  These issues mostly stemmed from trying to extend an unknown code-base with rather poor documentation as a good amount of brain power and time was spent analyzing the existing source code to figure out how to fit our new features in.  This was probably the first time in my programming experience that I had to learn what someone else's code did by reading it and it definitely emphasized the importance of good documentation.  Finally, this experience also made me realize just how essential good group members are.  When everyone did their part, the workload becomes much more bearable and the project can progress smoothly.  We did not finish with a lot of extra time like our own CLI project, but we did have enough time to double check everything to give ourselves the piece of mind that we did our best and that the product is up to our standards.  As a result, I would like to thank Eldon Visitacion and Jordan Takayama for their hard work throughout this semester.  It has been a pleasure working with them in group JCEV and I am looking forward to working with quality individuals like them in the future.