OPC (Other People's Code)

I recently extended a project I hadn't written, adding a few more features to it. I worked collaboratively with 2 other people using the IDPM (Issue Driven project Management) process. The three of us divided our task into more or less equal parts, and went about adding the desired functionality to the system. The system is a power an energy monitoring platform, and the functionality we added provides commands to set baseline, goals, and monitoring of those goals in terms of power and energy consumption.

During the entire development process, I was lucky enough to never once have a source repository merge conflict with any of my partners' code. I guess we all knew how to say out of each other's way, using package names and classes and encapsulation and separation mechanisms to make the code modular and flexible.

But the thing that most simplified our task was the build system infrastructure included with the system. It took care of dependency downloading, compilation, deployment, testing, automated quality assurance, and more. I'm talking about the Ant build system, which along with Maven, is the most used in the Java community and works very well with Java and its tools. The project came with a complete and modular Ant build specification, constituting about 10 Ant files (which are XML files using the tags in the Ant namespace), so that we were able to get off the ground and running within seconds of downloading it.

We did have to meet a few times though to sort out external interfaces and dependency issues, like what modules depended on what modules, and therefore which modules needed to be completed first. At our meetings we quickly got down to specifics and used an eraser board to write down pseudo-code, interfaces, and object definitions. One of my partners even took a cell phone snapshot of the eraser board for future reference.

Possibly even as useful as the automated build system was the continuous integration process we used to develop the system enhancements, a combination of the Jenkins build system and the google Subversion project hosting. Had we ever run into compilation or testing problems, we could have easily known who was responsible and could have easily rolled back the system to a previous healthy state if the problem could not be fixed.

The combination of automatic building, continuous integration, and automated quality assurance kept or code honest and its format uniform. One thing I found about working with quality assurance tools like Checkstyle, PMD and Findbugs, is that they frequently teach you about writing better, more effective and more correct, code. Many of the tips and suggestions included in books like "Effective Java" by Joshua Bloch will show up as warnings in PMD and Findbugs. It's great to have them there to remind you of when you're doing something unsound.

The whole process went so well, that I don't think we had a single failed build on the Jenkins server. Of course, I know that this implies that each one of us must have been running their Ant verify script locally every time before checking new code or configuration changes into the system. I know, that I can rarely make any change of more than a few lines to the system without Checkstyle, PMD, Findugs or Junit complaining. But this is good. I'd rather deal with one issue at a time than with dozens like I used to before I used unit testing on my code. And I'd rather QA tools force me to keep the code looking good and doing things the right way, as I code, instead of having to go back and do cleanup for hours on end. I used to hate that, and would often cut corners or delay until it was too late.

The more I think about it, these tools and this process are analogues of the things we do in our lives to make managing them more efficient and positive. Get some work done every day, don't push off unpleasant things to the point they pile up into a huge chore, and monitor your progress, so you don't experience any nasty surprises. It's common sense, and it's about time, the same stress reducing techniques used in real life, become mainstream in software development.

YATR

Yet another technical review....

I just recently conducted a technical review of a system, which to protect the guilty shall remain anonymous. It's an application that is packaged in a zip file, and in it are all the ant file trappings that characterize a structured java development process. xml files for the ivy dependency manager, for junit testing, for jenkins continuous integration testing, and for automated QA assurance with three tools by the name of PMD, Findbugs, and Checkstyle. Here are my findings.

Well, first I visited the project's home at the google code site, and browsed to the source tab, at which point Google helpfully reminded me of the svn command string to check out the code to my machine, which I did. After that I cd'd into the project directory and ran ant -verify on the project, and saw that the code compiled, the unit tests were passing, and the automated QA assurance tests were passing to. That was a sign to me that I wasn't looking at vapor-ware, which is always a plus.

Then I fired up the system, by going to a Main.java file that had a public static void main, because I just a strange feeling that that was the app's starting point. I was right. Application started right up, and I get a prompt offering me the choice of 4 nifty commands for finding out how much energy is consumed in some buildings in a campus on an overinhabited tropical island. Commands seem to work fine, but I'm a prankster, and I purposefully direct my mischief at this poor innocent application by entering:

energy-since Mokihana-A 2011-11-

See that last string awas supposed to be a complete date in the yyyy-mm-dd format. Well, the app didn't like that. It answered:

2011-11- is not a valid date, or date format yyyy-MM-dd.
Reason: java.text.ParseException: Unparseable date: "2011-11-"

That's offensive. Just because I'm a prankster doesn't mean I want to see the ugly Java underbelly of the application, which I was idealizing as a nice Ruby app, and now my fantasy is shattered and I can't get Java out of my mind. Plus, I suddenly got the urge to go pick up the dragon book and write a parser, when I need to be chugging along in my handsomely compensated technical review job.

Ok, when all is said and written, it's got to be admitted the app does what it says it would do.

Now on to another pressing matter: is it amenable to easy use and installation. Well, yeah again. It's google code site is elegantly furnished with all the delicate and succulent tidbits you'd ever need to know if you wanted to install the app. It's main wiki page even has a reference to the project it depends on, though the authors forgot to put a download link directly on the main page. No matter, though one extra click gets even the laziest of mortals to the complete download page, which in addition to sporting the app distribution file in zip format, also offers a complimentary style format file suitable for use with the Eclipse plugin, and meant to have the Eclipse IDE (sold separately) do much of the styling for us, that the checkstyle plugin will yell at us if we don't do the right way.

The google site for the project even has a wiki entry for the coding standards used in the project, so that these standards might live on in the coding after-life.

Ok, score another one for the gipper. The last thing every black belt technical reviewer checks for: can the system extended and/or modified?

Well, looking at the development wiki, I can see that it's a jiffee. The authors of the project have graciously enumerated all the development facets of the application, providing sample commands for building, running a code coverage suite, testing, generating documentation from the javadoc comments, deploying, and instructions for adding commands to the actual application. The wiki developer page also includes brief sections on the issue driven project management collaboration process used to develop the application and a link to the Jenkins continuous integration server that the authors used to keep the system healthy and test it in neutral territory.

I ran the JavaDoc ant task and perused the generated JavaDoc. I was impressed with the quality of the comments and also with the use of special JavaDoc features like code links.

After running the Jacoco test coverage tool, Was able to see that the authors achieve a very high code coverage rate, with most of the untested branches being in the test code itself.

I also surveyed the test code, and while it is extensive, I though the design could use a little refactoring. In particular, the authors chose to put all the tests that check that the different commands run successfully in one Test case. That file is already a little bloated and would necessarily become more bloated as new commands are added to the system. If the commands merit their own classes, then they also merit their own test case classes and files.

I checked the project's issue page, and saw that the authors had divided up the tasks very neatly into feature or issue based chunks. They even created issues to explain time off from project work and multi-day absences from the project.

Finally, I started looking at the source code, which I could tell from successfully running the ant verify target, was at least at a certain level of quality. Right off I saw that the code included several custom exception classes and that's usually a good sign since those custom exceptions can carry project specific information and make extending the application easier.

The code base is also pretty modular and I found no overly complex parts or overly nested control structures. All in all, this seems to be a well-managed and well-designed project. It does what it's supposed to do, it's easy to use and install, and it lends itself to being extended and modified.