Hi!
Here follows a technical review of Pichu's Hale Aloha Client, wherein a software system is tested in order to find and make the developers aware of problems they may've missed when they wrote their code. The test is based on three questions, one for each of the Three Prime Directives of software engineering, which, if followed, ensure that a program does something useful, can be installed and used by a non-developer, and can be enhanced by a developer who didn't write it in the first place.
Hale Aloha Client, the project under review, was developed as part of the software engineering courses at the University of Hawaii. The course has been a good bridge for those of us taking it to develop more sophisticated, complicated, larger programs. In this class, we have most recently covered continuous integration (CI), a set of practices which are designed to make software production quicker by focusing on steady, incremental improvements to the code base and ensuring that all contributors adhere to clearly defined quality assurance practices throughout the development process. Software engineering also covered issue driven project management, which is an effective approach to software project management for its simplicity and emphasis (like CI) on meeting small, achievable goals.
The Hale Aloha Client is the first of team project for us, as well as our first foray into CI and issue-driven project management. Accordingly, reviewing another team's results may yield deeper insights into these approaches, as well as crystallize what I've learned during this semester.
Review question 1: Does the system accomplish a useful task?
In a word, yes, but first, let's discuss WattDepot (whitepaper here), a project of Professor Philip Johnson's, for the continuous monitoring of power consumption on the UH campus and, later, in other places it will be installed. If you haven't been following my blog, you might not be familiar with WattDepot or aware of Hawaii's energy situation and the reasons we need to move quickly toward energy independence. WattDepot makes use of sensors installed throughout the campus, which feed energy- and power-usage data to a web-server. This information is made available by an API, which Team Pichu uses to provide for the client program being under review.
The program gives (what appears to the user to be) correct information for the queries it is set up to handle. If I were running the Kukui Cup, this would be a useful, simple tool for tracking the energy usage of the competing lounges and buildings. More broadly, the client would be a decent auditing tool for any entity with a WattDepot server.
Review question 2: Can an external user can successfully install and use the system?
Prime directive two is well met by Pichu's program, which conveniently comes bundled with a .JAR file, thus making compilation on the user's end unnecessary. Inclusions such as this make Prime Directive Two much more likely to be met. Most users are not software developers, and they would understandably balk at the prospect of compiling the code from the command line or within an IDE.
Pichu's Google Code front page makes the program's objectives clear, and provides sample user I/O to illustrate them. It is more elegant and descriptive than my group's is, and I am sure that a user would be better able to understand the purpose of their program from their first visit to its home. Also good for the external user: The UserGuide instructs the reader how to download, install, and execute the program, and a version number is included in the name of the project folder.
Pichu's implementation demonstrates ample robustness. For example, upon queries using past timestamps, for which the program does not have any data, the program nicely returns a "no data received" message. Given future times, it tells you it's "too early to retrieve" the data for such dates; given bad arguments, though the program doesn't give suggestions immediately, it prompts the user with the help command. Such stability is reassuring, from the user's perspective, and not having to re-launch makes the program easier to use.
Review question 3: Can an external developer successfully understand and enhance the system?
So, we have seen that the user can make the program work without very much trouble, but can a newbie get to know Pichu's program? First of all, the Dev's Guide is a very good start. It presents clear and comprehensive instructions on how to build the system from sources, what QA standards are being followed (regarding both automated and "manual" testing), and how a new dev might follow these standards. The format.xml file is linked, though the 314 coding standards to which we in ICS314 must adhere is not. The Dev's Guide specifies that the project is under issue-driven development and provides a link to the Jenkins CI server.
How to generate JavaDoc is not explicitly stated, but JavaDoc is mentioned in passing as they describe their use of the Ant build system. They are not generated as part of the default build process, which is probably not a "good thing." Invoking verify.build.xml or javadoc.build.xml generates them in the /build folder. When you finally have them, JavaDocs (which appear in the build directory after running Ant) thoroughly explain the packages, classes, constructors, fields—pretty much everything needed to understand the API. The names of these components make sense. I noticed that the processor class was not comprehensible from the JavaDocs alone. Reading them did describe the intended function, though, and perhaps for API documentation that is adequate. There is a stable command interface which integrates with the driver classes, which, in turn, are separated into main and processor packages. Such design decisions encapsulate and segregate the different components neatly, which should make extensive modifications (if necessary) less complicated for external and internal developers alike.
Building and verifying with Ant was successful and without errors. Jacoco reported 85% total coverage. The tests are not perfect, but they provide lots of coverage and are mostly very good. In general, they prevent a developer from modifying the source in a way that causes the program to provide incorrect results. For example, testCurrentPower checks that an greater than zero power is being used. Perhaps using equal to or greater than zero would be a better choice, as the test class would fail during a power outage. The test also checks that the class throws an exception when given incorrect arguments. Even the Help and Quit commands are tested. I'm impressed to see such thorough coverage.
Before trying to build from the source code within my IDE, I noticed one problem with the Java build path. The WattDepot client JAR file used a fixed path rather than a relative path, which made the program throw a ClassNotFoundException when I did attempt to build within my environment. Taking a cue from my teammate Russell Vea, I reset the path and was able to build successfully. The code has an appropriate number of comments and is lean without sacrificing intelligibility for brevity.
Part of the beauty of issue-driven project management is the explicit connections it makes between different parts of the code and the coders. From the individual issues, it's easy to see at a glance who to ask about the different parts of the project, were one to have specific questions about it: just about every important part of the system has an issue attached to it. It's also easy to see who has contributed the most. The Issues page shows that users Mrbarbasa and H.wk.cheng did the bulk of the work.
Other than on dates with server outages, it never took Pichu more than a half-hour to recover from a failed build. 9/10 randomly chosen commits were tagged with associated issues.
After performing the technical review, I feel well informed and prepared to contribute to the project immediately. That's coming up next: it's our final project for Software Engineering I.
No comments:
Post a Comment