Soapbox Rants and Raves

I recently found an interesting web site called Making Good Software. I really liked this guy’s site, he might just save me from writing down a lot of my own thoughts! Unlike my typical post, his are very short and easy to read. I highly recommend checking it out and popping through his other recent posts too. Nothing revolutionary, but just great reminders of how we should be thinking as we write new software. The following blog entries caught my attention:

• 10 Commandments for Creating Good Code
• 5 Tips to Improve Code Readability
• How to Become a Good Software Developer
• Comments are Evil
• TDD is not about Testing

The Comments are Evil statement really hit home with me… I have always said that code should basically be self-documenting. This statement is usually frowned upon some developers and managers; some people might think I’m just lazy. Farthest thing from the truth! By enforcing good coding practices with automation like Checkstyle, PMD, and FindBugs, combined with placing a high value on class and variable names, placing logic in the proper place, and keeping methods and classes small, most comments are redundant and typically provide little value. It was very interesting how the author associated comments with the DRY (Don’t Repeat Yourself) principal. Interesting thought, when your comments simply repeat what the code is already saying!

I also place a huge value on refactoring. I borrowed the image at the right to further highlight the point. There are many articles on the “Red Green Refactor” approach worth reading, helping to tie this all together. I guess one of my personal goals is always to create that elegant (simple and clean) solutions, which never happens the first time! Looping through R-G-R a few time helps achieve that elegance, and you end up with code that requires less comments.

Some of the comments in the Making Good Software blog are very interesting has well; many people throwing in their two cents, both pro and con on the value of comments. The author also states that comments cannot be completely eliminated. The code we write is never perfect and probably needs a little extra context to explain the hopefully infrequent imperfections.  I think the bottom line is to focus on quality code; eliminate the obvious, limited value comments, and comment the pieces that are truly intricate. If you are writing a lot of comments, then you better go back and look at your design, as something is probably not quite right.

Half of the fun of playing with Linux is trying out new stuff! I found a blog the other night that talked about Gnome 3.0 as well as installing it on Ubuntu. I don’t think that anyone would disagree that the current Gnome desktop seems a little dated; it is not vastly different from a pre-Vista Microsoft experience. Add in Avant Window Manager, Screenlets and/or Google Widgets, and you get a more modern Apple/Windows experience. I took the plunge and installed the 3.0 beta last week and have not looked back. I really like the interaction and thought the presentation was pretty slick. It is kind of funny how emotional people get (read the above blog comments) about change. People were going off on the usability and new look; saying it looked like Windows or Mac, or this feature was stolen from some other implementation. Who really cares? And why does everyone have to be so negative? I thought it was pretty creative!  Everything was very intuitive and easy to use; it might take a little more mouse movement to navigate, but the overall concept works for me. After using it for a couple days, I have learned there are multiple ways to navigate around, minimizing the clicks. The “Find” is one such short cut, you can quickly find an application in the menu system. It still has the good old fashioned alt-tab behavior to quickly switch between applications. The only option that was not obvious to me, was the virtual desktops. I’m not a big virtual desktop user any more (too much time on a Windows box during the day!); it did seam a little easier with the 2.x desktop (just needed to scroll the mouse wheel, I think).. Now you can dynamically (and easily) add new desktops through the activities menu (just click the plus icon). There is probably a nice short to to navigate between desktops, but I did not look for it.  One other usability note that is not completely obvious; you don’t actually have to click on the word “Activity” to get access to the menu, just push the mouse all the way to the corner and the menu pops up… Nice…

A couple of other interesting things I found on the Digitizor website.  Installing Chrome on Ubuntu and GIMP to be removed from next release of Ubuntu. I’ve also been playing with Chrome this week; it seems fine and fast. My “Wifi-based” Internet provider has so much latency, that it is hard to really hard to test “fast”.  I have been a fan of GIMP for quite a while and have only figured out the most simplistic functions to support my blogging; I guess I will have to give F-Spot a try in the future!

Several months ago, I got back on the code review bandwagon and jotted down some thoughts. As I worked with other teams doing “code reviews”, the lack of structure (from my perspective) got me energized to go back down this road.  We have been playing with the Crucible Code Review Tool for a couple of weeks now, but I’m not completely sold on what I’ve seen; I feel like I’ve missed something, but still think this is the right direction to be heading.

I first want to share a couple of links to some vendor papers that I think are worth noting, Effective Code Reviews (Atlassian.com), and Best Practices (SmartBear.com). I found two points that I wanted to highlight from these documents, both of which are about “preparation”. The following graphics were pulled from referenced links.
This first one really drives me crazy, but  unfortunately, this appears to be the way that most teams perform their “code reviews”.  First, the presenter/reader sets up a phone line for all of the participants to dial into, even if they all sit together in the same area! Next, the presenter sets up a “net meeting” and walks the team through the code; adding comments or making small fixes along the way. Maybe I have too limited of an attention span, but I don’t really commit to this type of code review, nor do many others from my observations. Inevitably, someone comes by with a question, or you get an interesting email or instant message; something to draw you away from what is being presented. To make matters worse, you have probably never even seen the code before and maybe don’t even understand the design. How much can you really contribute, other than noticing the most obvious issues? The above graph shows the range of code reviews, from a formality perspective. Not that the process has to be this rigid, but I think it is important to discuss the stages and roles of an inspection:

• An inspection follows a well-defined procedure that includes six stages: planning, overview, individual preparation, inspection meeting, rework,and follow-up. Certain participants have assigned roles: author, moderator, reader, and recorder.

Depending on the team, there is usually only one stage (meeting) and one role (reader). I personally feel it is much more valuable to explore the code and actually read the code in advance,  committed to providing feedback; I think the reviewer needs to physically participate, whatever that means: print off the code or browse the code on line, actually understanding the code, be engaged!

My second point is about preparation. I generally don’t think that most developers are very effective at “thinking on their feet”. It is really not about intelligence, but more about communication. Teams are typically very diverse,  both technically and it the way they consume (process) information. It can be very difficult to present code at a level which will be effective for everyone to understand and process. In my opinion, no preparation is equivalent to GIGO.

Previously, I thought it was more of the reviewers responsibility to make the process meaningful. I think the reviewers should (must) prepare before the meeting, just like they were studying for a test. Feedback must be returned before the “meeting”;  otherwise, there is no need to schedule the meeting. The purpose of the meeting is to discuss comments and determine the best solution for highlighted issues; this approach also helping to get everyone on the same page. The amount of preparation done by the presenter/reader can vastly impact the review as well.  If the reader simply “wings it”, it will be a generally unfocused and undirected presentation.
As illustrated by the graph to the right, the reader’s preparation has a dramatic effect on the code review process. The process of the author reviewing and re-thinking their implementation before submitting the code for review, provides another opportunity to discover problems before the inspection process actually starts, making the process even more efficient. How many times have you looked at your own code and said… “What was I thinking? This is not good at all…”  So, why know incorporate a “self-review” into the process as well?

I will wrap this up, so you don’t get too bored, my next blog will be on our Crucible evaluation. I did find a short blog that had a nice picture of the “Crucible Workflow“. This picture is where I’m striving to be, from a process perspective: collaboratively and iterative and ultimately actionable.

I seem to work on a variety of Java applications and find that unit testing is one of the most varied (implementation-wise) pieces of the development process. These applications, created by different development staffs, many which have evolved over the pass few years are all very unique… kind of makes me wonder why? That is a topic for another post!

One debate I always seem to encounter is around where to actually save the unit tests? Should we do in-package testing or rely on the public API. My preferences are pretty simple:

• Unit test should not be stored with the code, but rather created under a secondary source root. On my early projects, I created a sub-package under each package, called test, to manage the relevant files (tests and data). I later realized that I could simplify the Ant build process and enable in-package testing by creating a separate source tree. I have seen projects commingle the actual source code, unit tests, and even the test data files, all within the single source tree. This defaults the testing strategy to in-package testing, and discourages (or even prevents) API testing. I find this approach rather messy and unclear. This approach also complicates the Ant build process; at some point during the process, the unit tests, supporting classes and files should be separated from the actual deployable content.
• I like to name my secondary source root tdd. I know it is not widely practiced, but my hope is that if the developers see that TDD directory every time the open up their IDE, the concept might actually wear off! Maybe someday, one developer (hopefully more) will actually be challenged to write their unit tests first. With Eclipse and jUnit 4.x annotations, I seem to always start with my unit test, and sometimes even refactor code from the unit test into the actual class; kind of a high-bread TDD process, but the thought is always there!
• I also prefer the public API testing strategy verses in-package testing. This line of thinking always takes me back to the Testability Explorer. The concepts behind this metric enforce the idea public API testing and is worth a quick read. Add the Spring Framework to the mix, enabling dependency injection and I see little need for in-package testing. This is typically accomplished by creating a “test” package as the root of the secondary source tree, with sub-packages reflecting the package hierarchy of your classes to be tested. I truly believe that defaulting to in-package testing allows the developers to be very sloppy and even unaware that they are testing a specific internal implementation, rather than externalized behavior presented by the API… This is VERY bad practice in my opinion.
• If there is a need for in-package testing, then the sub-package structure of the classes to be tested can be recreated under the secondary source tree, maintaining a clean separation between the source and test cases. These test should be considered an exception to the norm, rather than common practice. I would hope for a 90-10 or 80-20 ratio, with a majority of the test falling under the test package root (in-package is the minority).

I am kind of tied to Eclipse as my IDE, but do play with NetBeans every so often. I think I could switch to NetBeans, my only real requirement is that the IDE must have Emacs key bindings; some habits are just too hard to break! NetBeans looks like an pretty good tool and seems to be very responsive on my Ubuntu box; I especially like the way it manages plug-ins.  One interesting thing that NetBeans does (maybe a little better than Eclipse), is manage unit testing. NetBeans will automatically create the secondary source tree, but seems to default to in-package testing. It is very easy to add the additional test package into the package structure to enable API testing. I also like the way that NetBeans separates the Test Libraries from the regular Libraries. I’m not sure how well this would work when you use a tool like Ivy, but does make it more obvious, as to which libraries are used for execution verses unit testing… If you do happen to generate a unit test from an existing class, NetBeans will generate more code than Eclipse. I’m not sure how useful this code is, but it does try to create the object under test, invoke the get() methods and perform assertions on the returned values. Might be more noise that it is worth, and anyway, you should be writing the unit test first!

The bottom line is that Unit testing should be easy and valuable. If it becomes too hard or complicated, it might be time to re-address how the unit test strategy is being implemented.

This was making me crazy the other night… I did not spend too much time on it, thinking is was just me. But, after upgrading my laptop and encountering the exact same problem, I knew there was more too it. It seemed like only the cancel buttons actually worked; all of the next and finish buttons did absolutely nothing, other then beep!  I soon realized that I could use the tab key and press enter to move to the next screen; but that did not make me very happy.

A quick Google search turned up several people with the same exact problem. It was kind of interesting. The Ubuntu developers did not want to take responsibility for the problem and said it was an Eclipse issue. The Eclipse community said they never had to do anything special for Eclipse to run on Ubuntu; it was looking like a stand off! I did find the official bug report filed with Launchpad.net, it says the problem is resolved. However, without overriding the following variable, Eclipse is not very usable.

export GDK_NATIVE_WINDOWS=1

It also appears that this problem is affecting many other tools on the new 9.1 release as well. This simple fix will get you back into action, without having to wait for the real fix.

Not that I’m a big fan of the whole “Anti-Pattern” concept, but there is some subtle irony in the title of this post; some of my coworkers will actually understand. Sorry about the mystery for the rest of you, but I think this post is really relevant for those trying to use Spring for the first time. After building my first Spring-based application, I was on the fence concerning Spring’s actual value. Obviously, I made lots of mistakes in my first implementation; I think many of the following anti-patterns can typically happen on your first Spring project; my goal is to make you aware of these pitfalls, such that you can skip past the mistakes made by myself and others.

Interesting Thought Tangent? While looking for the title to my post, I have found a little snippet that calling “Spring a direct attack on J2EE“. I thought this was a unique way of describing the Spring Framework. For sometime now, I have been on the bandwagon to simplify the development practice through Spring (Spring Core, Security and Remoting). I never really thought about Spring as another religious battle front; such as the classic emacs/vi or mac/pc wars. In essence, I was picking a side: No more J2EE! I guess it was not obvious to me before today, as I really can’t escape the J2EE container; I’m are required to deploy in a J2EE container, even though I make no use of its capabilities; a Servlet container is all most of us really need! Just an interesting thought! Agree or Not?

So where to begin, I guess the first question is: Why do you want to use Spring? What service(s) will it provide for you? I think many developers simply wanted to slam it on their resume! Let’s start with the the most obvious use of Spring, Dependency Injection (WIKI, Fowler). I think this is the hardest thing for most developers to actually understand! If you think you are just writing XML code to create your instances rather than writing Java code, you have already missed the boat. I really believe that most developers have not actually taken advantage of DI in their applications.  They just use Spring to create an alternative static (hard-wired) bean creation strategies. Just for fun, I thought I would highlight some anti-patterns I have seen used before and hopefully never again!

Create a Factory. Factories are so 1990. This is one hurdle that some developers have a tough time understanding. They continue to think about creating objects via factories. There is NO need to ever create a factory when using Spring. Spring is essentially the a super factory, plus it is actually responsible for the life-cycle of those vended objects. There are scenarios where you need to specifically create objects that Spring manages, in a loop for example; but these are very uncommon. The proper way to solve this problem, is to create a bean that is ApplicationContextAware.  When this bean is created (by Spring itself), Spring will set the application context on this bean. Now, you have the ability to ask for any bean that Spring is managing.

Ask Spring for objects. This is probably the toughest habit to break and is easiest pattern to get stuck in. This is especially true if you are trying to integrate Spring into an existing project and is your first attempt at Inversion of Control. You will have a much better chance understanding these constructs, if you can start from a clean slate (or at least create a bunch of samples). Spring done right, is truly is a different way of thinking. For example, when working with a context-aware Servlet, you fundamentally NEVER need to ask Spring for a single instance; this is almost a perfect example of IOC and DI.  The whole point of DI is the INJECTION. It is not about ASKING for an instance, it is about being GIVEN an instance;  throw in the IOC principle and your bean will be invoked at the RIGHT time to provide the appropriate behavior.

Domain Object DI. This was an unusual one for me. I recently observed a project that used Spring to created multiple static Singleton factories to vend out a variety of instances, each factory with it’s own Spring context file. Needless to say, this application was far from easy to understand. To my surprise, there was even a factory specifically implemented for creating the business domain objects. Why this was done is still a mystery to me and seems to violate the true spirit of Spring. Why would I ever want to call DomainFactory.getNewWidget() or DomainFactory.getNewGadget()? The configuration had the domain beans defined in a separate Spring context file and oddly, used static methods to initialize specific properties of these new bean instances. There was no way which enabled the XML configuration to be overridden, allowing for different implementations. Worse yet, you were tied to the initialization behavior of the factory methods! Depending on your definition of a domain object, I see very little reason domain object dependency injection.

Use Ant to create Spring Configurations. This is an interesting use of Ant in a Spring-based application. The idea here is to generate the Spring configuration and properties file from an Ant task, to specifically configure the context files to each deployment environment. They values are essentially baked into the application and unchangeable.  It is bad enough to substitute property file values, but some developers actually substitute bean name references. This might be a little hard to follow, but the Spring XML configuration would define two different implementations of the same basic function, each with its own name. When the application is built, the Ant tasks would substitute ref=”bean1” for some environments and ref=”bean2” for others; everywhere that implementation was referenced in the configuration files. Call me crazy, but I don’t think this what the Spring creators ever intended!

As I have developed a better understanding of Spring and how to take advantage of it features, we have evolved our Spring applications to a state of “environmental awareness”. Using this solution, all of the context and property files are packaged into the application, for all known environments at build time. This enables us to build the deployment image (jar/war file) one time, using simple Ant tasks, no more templates, no more substitutions, no complexity. At execution time, Spring is now intelligent and can determine it’s execution environment; we can use specific property files for specific environments, as well as use alternate implementations (via DI) for each environment. This is where DI really pays off, allowing us to use the appropriate objects, not just properties, but objects for each environment! No code changes, no crazy Ant tasks, you build once and deploy anywhere. I think this is actually pretty slick and what Spring (core functionality) is all about.

I do have to put in a plug in for testability. Taking advantage of jUnit 4.x annotations and Spring integration, makes unit testing a snap. Using the @Resouce annotation to inject everything (instances) you need into your unit test is amazingly elegant; unit testing could not be made any easier. This approach allows us to have highly controlled, customizable execution environments; we can seamlessly manage unique configurations for local development, continuous integration, as well as any actual deployment environment almost magically.

Apparently, I like to live dangerously; last week I upgraded my Ubuntu box to the 9.10 beta. Unlike my last upgrade, this one went off without a hitch. Not surprisingly, I seem to have 100MB updates every other day, but even so, the box is rock solid. The only annoying thing is that many of the updates make me reboot, I almost feel like I’m running Windows! The list of new features is quite extensive. The most obvious change appears on the initial reboot; the login manager and upgrade to GNOME desktop environment. With every release, the user experience becomes more and more polished.
Throw in Avant Window Manager and Screenlets, and you have a really nice looking, easy to use desktop. Other than doing my checkbook (which some might call old school), I have no need for a commercial OS. Everything I need to do is available, Open Office, GIMP, Empathy, Firefox, etc.  This release included some work around boot performance and changes to the login manager. I didn’t really notice any boot time differences (this might not be obvious on a Quad-core, SATA machine), but the login manager is much nicer. I can see this being a big win for people that share a computer at home and user multiple accounts.

Presumably, in a attempt to create another income stream, Ubuntu created https://one.ubuntu.com, personal storage in the cloud. I have been recommending DropBox to my friends, as it has worked very well for heterogeneous environments, supporting all of the major platforms.

There are numerous technical advancements, but my primary motivation is to have a usable development box, one that delivers me a user experience similar to the expensive options and provides all of tools I need (database, Servlet container, web server, etc).  I have been using the 64-bit version of Ubuntu for over a year, it has never been as “issue free” as the 32-bit version I run on my old laptop. However, it is getting much better. I finally have Flash integrated perfectly, this has been a persistent issue for me… I recently tried to get the new Hulu desktop working, but I think it wanted the real Adobe Flash Player. I had been using one of the alternative, non-Adobe implementations and it was quite flaky and unreliable. I finally did a clean install of the Adobe plug-in and am seeing much better rendering; I have not had success with the Hulu Desktop yet, but Google Analytics, YouTube, Hulu, Pandora, Wordpress, all web sites that rely on Flash, work perfectly for me now.

So far so good with my upgrade, I’m much happier with this release. Hopefully, your upgrade is as smooth! WorksWithU was an interesting site I found this morning, it seemed to have a lot of information on the upgrade and Ubuntu in general, give it a look!

I like anything that gives Apple a little jab… and am looking forward to Verizon releasing some interesting new phones. Verizon just created a new sub-site, http://www.verizonwireless.com/droid. I think it is actually a pretty good campaign, “iDon’t”. I have been using Windows Mobile for many years, and I will be the first to say that it has be be considered a complete failure; but similar to the old Palm OS, there have always been a multitude of free applications with no Steve restrictions. My primary need for a Windows-based phone was the integration with Outlook, which allowed me to sync my calendar, contacts, email, etc; which did work flawlessly. I have never been into the whole Android thing, as I am no fan of “single” source solutions, such as that iThing. But, now that Verizon and several other carriers are planning to release phones, and even Acer has released a new Android-based netbook, I’m starting to get a little more interested!

For whatever reason, I have been using a lot of Java Regular expressions at work lately; I started taking advantage of the grouping abilities provided by the standard Java Regular Expression implementation. I am certainly no RegEx expert, especial after reading this overview of backreferences and forward references! I use them every so often, probably not as much as I should; I know just enough to be dangerous! With my new exposure to grouping, I will probably use regular expressions much more frequently. Historically, if I needed to split a String into pieces, my goto class was the StringTokenizer. More often than not, I now use the String.split() method; you use create a simple regular expression and the method returns an array of the split values;  It is actually easier to use and handles the case where no matches are discovered fairly well.

If you are going to create and use regular expressions, you are probably going to need to test them. I have been using web-based expression testers for several years; here is one that I use often; Tonight, I found a FireFox plug-in I like ever better!

The point of this post was to show how easy it is to capture data using regular expressions. I created a little class to decode an id and status from a String. As illustrated in this simple example, you can use the Matcher class to do more than simply determine if the regular expression matched. With the addition of round brackets (parentheses) to the regular expression, we can actually capture the matched values in one simple step. This approach can also be used to capture optional values, the id and status, as in the included example. Unlike using a tokenizer or the split method, the Matcher class maintains the expected positions of non-specified, optional values; simply including an empty String for the optional attributes, when they are not provided.  As you can see the following Eclipse debugger screen shot, the groups are easily accessible, even allowing you to build nested groups, as my example demonstrates. You can play with the example or give the Matcher JavaDoc a quick read to learn more about how this class works.

public class StringDecoder {

    private static final Logger LOGGER = LoggerFactory.getLogger(StringDecoder.class);

    private Collection<String>  transactionIdentiferPatterns;

    public class Result {

        private long   transactionId;
        private String status;
        private String filename;

        public long getTransactionId() {
            return transactionId;
        }

        public void setTransactionId(long transactionId) {
            this.transactionId = transactionId;
        }

        public String getStatus() {
            return status;
        }

        public void setStatus(String status) {
            this.status = status;
        }

        public String getFilename() {
            return filename;
        }

        public void setFilename(String filename) {
            this.filename = filename;
        }
    }

    private class Match {

        private String[] group;
        private int      start;
        private int      end;

        @Override
        public String toString() {
            StringBuilder sb = new StringBuilder();
            sb.append("Match [end=" + end + ", start=" + start + ", value=");
            String comma = "";
            for (String s : group) {
                sb.append(comma).append(s);
                comma = ",";
            }
            sb.append("]");
            return sb.toString();
        }
    }

    public void setTransactionIdentiferPatterns(final Collection<String> patterns) {
        this.transactionIdentiferPatterns = patterns;
    }

    public Result decode(final String filename) {
        Result rc = null;
        for (final String pattern : transactionIdentiferPatterns) {
            final Match match = find(StringUtils.trim(pattern), filename);
            if (match == null) {
                LOGGER.warn("No match found using pattern [{}]", pattern);
            }
            else {
                LOGGER.info("Mache found {}", match);
                rc = new Result();
                rc.setTransactionId(Long.valueOf(match.group[2]));
                rc.setStatus(match.group[3]);
                rc.setFilename(filename.substring(0, match.start) + filename.substring(match.end));
                return rc;
            }
        }

        return null;

    }

    private Match find(final String patternStr, final String valueStr) {

        final Pattern pattern = Pattern.compile(patternStr);
        final Matcher matcher = pattern.matcher(valueStr);

        if (matcher.find()) {
            final int groupCount = matcher.groupCount();
            final Match match = new Match();

            match.group = new String[groupCount + 1];
            for (int i = 0; i <= groupCount; i++) {
                match.group[i] = matcher.group(i);
                if (i == 0) {
                    match.start = matcher.start();
                    match.end = matcher.end();
                }
            }

            LOGGER.debug("Good {}", match);

            return match;
        }

        return null;

    }

    @Test
    public void simple() {
        Collection<String> patterns = new ArrayList<String>();
        patterns.add("(###OID([0-9]+)([F|S]?)###)");
        this.setTransactionIdentiferPatterns(patterns);

        String name = "SomeStuff###OID122325F###.csv";
        Result result = this.decode(name);

        assertEquals(122325, result.getTransactionId());
        assertEquals("SomeStuff.csv", result.getFilename());
        assertEquals("F", result.getStatus());

    }
}

Ok, that is just about enough Hudson for this month, unless I get fired up about Selenium and try out the Hudson integration! I did find one more useful plug-in this week, the Task Scanner.  Because I tend to check in code early and often, my code is typically in an incomplete state; you will tend see a lot of TODO or FIXME comments in the code. Managing these task inside of Eclipse is easy enough, but I thought it might be interesting to also monitor them on Hudson’s dashboard.

The plug-in is very easy to configure and allows you to specify thresholds on the number of open tasks. Like most other plug-ins, it generates configurable trend graphs and provides a convenient task browsing screen.

Here was an interesting blog post that shows how you could use the plug-in to determine how messy your SVN merges will be… kind of cool..