In a galaxy far, far away there was a tool that I really liked, but never pushed into my builds. Nevertheless, it changed the way that I thought about code, and how I thought about my tests.
That tool? Agiledox.
The idea is simple: a class under test ("Foo") is normally tested in a class that's named after the class under test ("FooTest"). If the test names reflect roles and responsibilities, we can automatically generate documentation. The way to do this is to take the test names, strip the word "test" from them and un-camelcase the names. That is:
public class FooTest extends TestCase {
public void testShouldDoThis() {}
public void testShouldDoThat() {}
public void testOnTuesdayShouldMeltdown() {}
}
becomes:
Foo
Now, the twist is that there's something missing here: an explanation as to why the Foo class was written in the first case. The class under test sometimes contains a meaningful top-level javadoc. It makes sense to drag that in too.
Voila! Documentation!
Docs on their own are pretty meaningless, but I like the fact that this is a handy way to drive a conversation about OO design, testability and code quality.
Well, it's been seven days, and I'm now back from holiday and plugged into the Net again. Looks like it was a big week: IE 8 was released, as was Street View in the UK (finally!), IBM is in talks to buy Sun (for Java and the consultancy revenue it generates, presumably?) and Battlestar Galactica comes to an end (though it's still not available on itunes yet, so no spoilers please!)
Perhaps I should take some time out more frequently?
Portakabins are wonderful things. Temporary buildings that are designed to fill a certain need, but only for a well defined period. They are also terrible things: they're "good enough" to the point where people sometimes use for far too long, despite the fact that as permanent accommodation a properly designed building is far better.
Of course, there's a software development analogy in here. Teams often throw in a temporary fix to a problem that's "good enough" for now. Life would be a lot more pleasant if the job was done properly, but perhaps the team is bridging to a new architecture, or time pressures mean that as long as "this code-path here" works fine then it's okay.
The problems start when that portakabin is never removed --- who has time to go back and clean up things that are working? Someone comes along, looks at this thing that was created as temporary hack and decides that, actually, yes, that is how code should be written. Oh! The pain of Example Driven Development! Suddenly, what should have been a quick fix turns out to be how things are done.
Perhaps this explains my visceral dislike of seeing temporary hacks being thrown into a code base; we're just saving up long term pain at the cost of doing something we're not happy with today. Reminds of the saying "Of course a shortcut takes more effort. If it didn't it wouldn't be a shortcut, it would The Way"
You've maintained a temporary fork of a library for a while, but you need to ship your product to external customers, or the developers of the library aren't interested in your fixes, or you're just feel that what you'd like to do most with your precious free time is to maintain a library.
The only decent thing to do is make the fork permanent.
There's a whole bunch of choices to make here, but they all start with the same action: changing the package name. Unless you're officially taking a project over, this single action means that other teams can make a reasoned choice about migrating from the original version to yours. It also means that as your fork and the original diverge teams don't have to fight about which library they should be using.
If you're forking so that you can ship a product or project, then changing the package name decouples your project from the forked library's release schedule: you become free to ship with snapshots with your fixes applied. If you're forking because the underlying library has some major issue that's not being properly addressed, you put yourself in a great position to open that project up to other contributors and allow yourself the freedom to change APIs as you see fit. Lovely.
Actually, the case where you're forking to allow your product to be released is an interesting one. It's similar to the case where you want a temporary fork, in that you probably want to continue tracking the current HEAD release so that you can fall back to the original library as soon as possible. In this case, the best thing to do is to automate the package renaming; write a script that does the grunt work of renaming the packages. You can then hook it into the process described in my previous post, meaning that you have the advantages of your own private world with the opportunity to fall back to the original library when necessary.
Which is nice.
So, you've finally run into a situation where you want to upgrade one of your project's dependencies but one of your other dependencies prevents you from doing so. In the ideal world, things would just work seamlessly, and you could just grab the latest version, but sometimes life's just not like that.
Oh well. Time to fork that library!
Before we begin, we have a choice to make: is this a temporary thing, or are we never planning to return from whence we came? It's extremely unlikely that you're actually interested in maintaining your own fork of a library indefinitely, so let's work our way through a temporary parting of the ways. Life is made simpler because there's probably just a few things that are wrong or need changing and we'd be pleased to roll back to the original library once those small issues are fixed. Everything should centre on allowing us to get back to the ideal situation.
The first step when forking is to write a failing test that exposes the missing functionality. Maybe this test is just "when I new up this object, the constructor throws an exception". Maybe it's "when this method is called, the wrong value is returned" Whatever it is, encapsulate it, because once this test passes with a later version of the original library we're going to drop our fork. Write a test per feature of bug that you're planning on adding or fixing.
Until then, we're going to need the source. Check it out from the project's source repository. If you can't do that, figure out how to get the source. You're going to need it, because the next thing to do is to fix a single failing test. Not all of them. Not five of them in one go. One failing test. Create a patch between the original source and the version that causes your test to pass. Keep that patch under your source control system, next to the library. Now repeat the process for each failing test. This way, there's a patch per feature of bug.
The reason for doing this becomes clear when we upgrade the library. The process becomes:
Taking a step back, the whole process boils down to three steps:
As part of being a "good citizen", and to minimise the amount of time that your forked version of the library exists for, send the failing test and the fix to the project owner.
But what would we do if we want to ship with a forked library? Or what happens when your differences are too great? That, dear reader, will be what the next post is about....
How hard can it be to use an Open Source java library in your project? I mean, all you need to do is drag the JAR on to your CLASSPATH and your done. Oh right, yeah, fine. You need the dependencies too. And the dependencies of any dependencies. And so on.
But I mean, it's not hard is it?
Certainly not to start with. But then there's a new version of the library that you could use. And it deletes an API you use. Or you're not sure whether it'll work properly. Or it's a bad day to upgrade the entire codebase. Or you have no idea whether something will work or not. So what do you do? What do you do?
Don't do this: have a second copy of the library in your source tree. That's dumb. That's dumb because you're depending on classpath ordering, which may or may not happen consistently.
Which means that you need to have only one copy in your source tree at any one time. This also means that if you need the latest and greatest feature from a library, you're effectively becoming something like the Apache Gump, and sometimes something's not going to play well with something else. That's when it gets fun. That's what I'll cover tomorrow....
I think it's fair to say that the iPhone is the best phone I've ever owned, but with the release of the new 2.2 software update, it just got a whole lot better.
I'm away from home right now, and will be for some time, and that means that I've had to make choices about which bits of techy paraphernalia I can bring with me. Unless I'm willing to do myself an injury, I can only really take one laptop on the road with me, and given that I'm here for work, it's the work laptop that came with me. Not, and this is important, my personal laptop.
It's important because I also brought my iPhone with me. Before I left, I synced up as many podcasts as I could, but some of these, especially the news podcasts, go stale pretty quickly. Without being able to connect to my personal laptop, there wasn't a mechanism to download new podcasts, rendering the latter parts of any trip devoid of fresh news.
Aside: I almost said "fresh content", but felt a little of sick at the back of my mouth, and so have skillfully avoided management-speak once again. Hurrah! Now back to the main thrust of this post. Mentally delete this paragraph and append the next one to the end of the last one, please.
No more! With the 2.2 release, I can download new podcasts, either of the set that are already synced with my iPhone or by using the built-in iTunes app on the phone to pick and download new ones. Sure, it would be nicer if this happened automatically, preferably using the same preferences I have on the desktop version of iTunes, but just having the option of downloading something new is a real boon.
Of course, to get this feature, I need to be able to install the 2.2 software update on my iPhone, and this is where Apple have once again done the Right Thing. Although I can't sync the iPhone with anything other than my personal laptop, I can do a software update on any machine running iTunes. It's not the sort of feature that you need on a regular basis, but when you find out it's there, life becomes a little more easy. Finding out that this capability is present brings me to another feature of the iPhone that I like: the ubiquity of the power lead, and the fact it plugs into the USB socket. It's a little roundabout, so please bear with me.
Back in the day, it was virtually impossible to run out of charge on a Nokia phone. Everyone had one, and because of this, everyone had ready access to the charger. Better still, all the phones used the same size connector. Wonderful. And then Nokia changed the size of the connector, and people started buying other makes of phone. Suddenly, it became a lot easier to run out of charge, and I started to have to bring my Nokia charger with me, along with the adapter so I could use it abroad. And a second adapter for my laptop. Or, as I did on a regular basis, you can juggle the foreign plug adaptor, switching to using it to charge the item with the least power as necessary.
Frankly, having a Nokia phone had become a major PITA.
The ideal for me is to be able to take one power adapter and to be able to charge everything from that. Ideally at the same time. The iPhone, the model of convergence in action, allows me to carry one device instead of two to meet my music-listening, phone-calling desires. It uses the same cable to charge and connect to the Mac as the iPod always has, and given the ubiquity of the iPod, that means that this particular lead is easy to get hold of. Because it plugs into the USB socket of my laptop (or, indeed, any machine) it's possible to charge that and the lappie from the same adapter. As a quirk, when you plug an iPod into a machine, iTunes often starts up, and will tell you about any new updates that might be present for the shiny piece of Appleness you've just plugged into the Intel designed port.
I'm sure that there are other goodies to do with the iPhone that make it indispensable --- the mail client, with its ability to access emails even when offline, has saved me a whole host of grief, and my wife and I now no longer bother to know where we're going actually is until well after we leave the house thanks to the combination of GPS, Google Maps and access to JourneyPlanner --- but the universality of access to the ability to charge the device, coupled with the ability to get new podcasts, means that the iPhone meets all my traveling needs for now.
It would be nice to be able to tether my laptop to its 3G connection sometimes....
Just a quick post on this, because I find these two concepts useful when talking about dependency injection.
Permanent Coupling: Where you can't imagine the object existing without this dependency. The crass example is "a person has a brain." These should be injected via an object's constructor and I'd expect to see them appear in the app's config files (Guice, Spring, Picocontainer, whatever)
Temporal Coupling: The dependency is a temporary collaborator of another object, but you can imagine the object being just fine without it. The example would be "a person uses a watch to tell the time" (no puns were injured to bring you this example) I would expect to see these temporary collaborators to be visible as part of a method signature. I humbly submit that injecting these dependencies in the constructor is a mistake.
It's taken me a little googling to find this out, but when a "git rebase" halts because of a merge conflict, the way to deal with it is by manually editing the file, correcting the merge and then doing either a "git add" or "git rm" of the affected file, followed by "git rebase --continue"
It's all so obvious now.
I must be late to the party, but Gears finally works on Firefox 3, which is a Good Thing considering that RC3 has just been released. Yay! On the downside, Google Reader isn't showing up properly when I access it offline. Oh well, I'm sure that it'll be fixed soon.
On a related note, I've had the opportunity to delve into the Gears codebase. There's some pretty cool stuff in there, and if it wasn't Open Source it wouldn't have been so easy to use it as a learning tool. It's a pretty hefty amount of code, which makes getting to grips with it a slightly intimidating experience, but it's organised well and once you've started it starts to make more sense.
I find myself wondering how easy it is to attract new developers to the project: I know that the number of languages used in WebDriver puts some potential contributers off, and we've got far less "mass" to deal with. I'm working on the theory that the modularisation of both projects helps make getting started easier, and once people are involved it becomes less daunting to tackle the areas that seemed too hard to even look at.