API Lessons

A co-worker came by my desk at work today to ask a question about a software component that I had been involved in designing and implementing. The more that we talked, the more his questions turned into complaining about the component design... primarily it's API. Now this kind of bothered me at the time, but the more I thought about it the more I came to realize that he was right - and I think that I know why.

While I haven't been directly involved in maintaining that particular component, I can still remember the project quite well. It was a relatively small project to design an infrastructure utility that could be re-used by various larger applications. There was no user interface (graphical or command-line) - just a bunch of Java classes that were bundled as a jar file for other development teams to use when they needed this certain functionality. I think that part of the problem was that without that standard user interface, we ended forgetting that our product still had a customer: other developers within the organization.

While there are lots of important things to remember when designing and building software, there are a couple of items that I think deserve extra emphasis when writing a component with a programming API - and writing them down now will help me remember them next time:

Don't wait until the internal design is complete before designing your API.
You will end up with an API that is far too tightly coupled to your internal design (can anyone say Leaky Abstraction?). Looking back now, I realize that during all of those weeks of design and development, we never once had a discussion on *how* the "customer" was going to use our beautifully designed piece of software. Of course we all knew that there would need to be an API for our component (we weren't completely clueless). It was shown as a nice thin layer on our architecture diagrams. But no one actually designed that API until the implementation was partially complete. I use the term "design" quite loosely here, because I honestly don't know how the API came to be, it just kind of appeared in our source code repository somewhere along the way.

USE your API before it's final release.
Write a sample application, or some extended functional tests - whatever. If you use it before you release it, then there is still time for change those pieces that looked good on paper, but don't really work in the real world. I am ashamed to admit that to this day, I have still never written any code (other than some isolated unit tests) that actually used the component that I helped to build. As far as I'm concerned, that's the equivalent of writing a web site in a text editor and never actually loading it into the browser and clicking your way through!

So, whether you are writing a more traditional application with a user interface, or a more technical component like a programming library - don't forget about your customer.

Oh yeah - it wouldn't hurt to read up a bit on API design before starting, like these slides (pdf) from Joshua Bloch.

Active Vancouver Weather

The Vancouver area has been getting some wild weather recently. There were some heavy rains a week or so ago that resulted in a boil water advisory that has lasted over a week for some people. Now on the heels of that excitement comes a major snow storm!

I went for a walk in the evening and snapped a couple of pictures. I wanted to capture the natural look so I turned off the flash and slowed down the shutter speed on my little point-and-click camera. The results were very bad... this picture is the only one that is even moderately acceptable:

From Snow - Novemb...

Us Vancouverites are typically pretty inept at dealing with snow - especially when it comes to driving which should make for an interesting drive into the office tomorrow.

Update: The boil water advisory has finally been lifted. And I didn't have to battle the morning commute in the snow because I am working from home today.

Blogger (Beta) and FeedBurner

So since I have a blog now, I thought that it would be a good idea to register the blog feed with FeedBurner. It's a pretty simple process - and the good folks over at FeedBurner even have some Blogger-specific instructions. Unfortunately, the instructions aren't as simple as they can be when it comes to the part entitled "Promoting your FeedBurner feed on your Blogger site" - which I only figured out after wrangling with Blogger's HTML template for a while.

You see, the instructions from FeedBurner tell you to "edit your blog's HTML template directly" in order to provide an easy way for people to subscribe to your feed. Unfortunately, this is a bit misleading. Maybe that is the way that you had to do it with previous versions of Blogger, but now you can just use the Page Elements feature instead:

1. go to your blog's Template tab
2. select the "Page Elements" section
3. select the "Add a page element" link (I created one in the blog sidebar),
4. give the section a Title, then paste the FeedBurner HTML snippet directly into the Content section.
   
5. Done!

That's progress.

Hopefully Late *is* Better than Never.

I have been reading and participating in blogs for a few years now, but seemed to never bring myself to actually start one of my own... so here I am, late to the party.

I guess a short introduction would be worthwhile. My name is Jeff Smith and I am a software developer in the Greater Vancouver area of British Columbia, Canada. I expect the content of this blog to run the gamut of topics including hockey, software, technology and miscellaneous personal ramblings.

I apologize in advance since the quality of the posting is going to be pretty erratic until I start to get the hang of it, so bear with me (notice how I am writing this as if someone is actually reading, I never really considered myself to be such an optimist!).

Now that the proverbial ice is broken, let's get going. It feels good to finally join the conversation.