Best Practices

Beware of unused variables

September 5, 2011 By Jason

When you’re making changes to a system, for the love of all that’s programmable, please be thorough.

If you’re changing a function, make sure you’ve cleaned up any variables that aren’t being used anymore (your IDE might be able to spot these for you, in which case there’s not a lot you can use for an excuse.)

If you’re changing a class and it’s internal framework stuff that won’t be used by anyone outside, make sure you remove functions if they’re not being called anymore.

If you’ve refactored global configuration variables or settings, make sure you’ve deleted all trace of them if they’re really gone.

If you don’t do these things, the next person to come along is going to totally miss her estimate on account of not realizing how many land mines need to be stepped around, and each one means more time added to the project, either in a big chunk right away by dealing with what you should have done already (and the testing and QA overhead that goes with it,) or in little increments every time anything around your old work needs to be touched (“what’s this? Oh, I don’t think it’s used, but I’m not sure…”)

Ask me know I know this…

And do all of these things right away. Because if you wait, even a little bit, you’re going to find yourself in the same position as the new guy.

Ask me how I know that (in a smaller voice, at least in recent memory.)

The “I thought we might need to bring it back” defence doesn’t work in a source control environment. Every line of code you ever submitted is still there in the repository. So why not keep the really embarrassing stuff out of the head?

(And don’t get me started on how documentation lags the code… Yeah, it’s been a fun long weekend refactoring.)

Dealing with external platforms: the smash and grab pattern

May 27, 2011 By Jason

There are times where you do something once, and it feels like an ugly hack, but then you keep doing it on other projects because you just can’t figure out a better way, and then you talk to a few more programmers, and it turns out that what you’re doing is pretty much the best approach.

I don’t think all design patterns are born this way, but that’s how this one came about. Here’s the smash and grab pattern.

Basically, when you have to interface with an external system, whether it’s a data API or more of a platform like a Facebook or Salesforce app, you want to get what you need and get out as fast as you can. Don’t try to modify everything you’re doing to suit the platform, just take the data that you require and port it over to your core framework as early as possible.

For a basic API, we’re talking about putting the data in a format that’s consistent with the rest of your application. For a more intensive app, you might be looking at a thin iframe layer or something.

It’s an extension of the adapter design pattern, basically, but adding a “take what you need and get out” mentality underlines the point that this interface is not the basis of your application (well, it likely shouldn’t be anyway) – your core business logic, other integration points, and future plans shouldn’t be relying on one interface to set the tone for everything you do.

And for the record, I’m not a design pattern guru. They influence my work and I’m sure I could explain my code using the basic styles, but I don’t approach each problem with a checklist or try to make them fit. They’re handy tools for describing core concepts, but in earlier years I found myself trying to make sure every class had at least one design pattern represented, and just like how the smash and grab reminds me that I shouldn’t rely too much on any one data source, I also need to remember not to rely on patterns for everything I consciously do.

The web’s made it easy to get design pattern information, but I’m still glad I have my Gang of Four book. For an intro to the core concepts, you could do a lot worse than Head First Design Patterns. [affiliate links]

Quick tips for demos and mocks

May 17, 2011 By Jason

A few quick ideas that came out of some conversations at Rails Pub Night:

iPhone web demos need icons

Nobody wants to wait for you to load up your example code. Make a folder of links so you can bring up the sample quickly instead of opening Safari, typing in the URL while juggling something else you’re holding (yes, last night it was beer,) and then waiting for the wireless to crap out. Launching from the home screen gets you right to that delightful no signal stage. Which you then deal with by…

Have video backups of everything cool

If you don’t have wireless access, your web-based demo might suck, so make a quick screencam movie of anything you need to demo and keep it on your desktop, USB key, and mobile device. This is going to sound 30% stupid, but if you demo your app via a video playing on an iPad 2, it will seem much cooler than if it was running on a computer where people could actually use it.

Use those same videos for mockup presentations

Giving someone a link and waiting for feedback can result in… interesting distractions, especially if it’s an early mock where some of the content is placeholder. Adding an audio track lets you walk someone through a feature while also being able to explain what’s not done. Before you send something like this out though, be sure to find out if your intended recipient has a sound card and/or headphones.

Use GotoMeeting for more structured presentations

You can do a more interactive presentation than you can with the screencam technique if you use a desktop conferencing solution like GotoMeeting, which I think is around $50/month. This means you have to actually schedule the call, but allows for a much more in depth discussion.

That about does it for now. And yes, these are notes to myself as much as they are to you or to your programming team.