• What Did You Break?

Tue 03 September 2013 - 14:11:10 CDT

I recently worked on a consulting project where I was brought in to carry some embedded software across the finish line. There was more work than they originally thought–not an uncommon sentiment–and the timeline was growing increasingly critical. (When isn’t it?).

The project seemed straightforward on the surface. “We have a legacy machine and legacy code base. We need to update the processor because we can’t get the old one anymore. So we also need to update the firmware because a lot of it is hardware dependent.” No sweat. No surprises here. Code in in C, so it’s reasonably portable. Find the hardware-dependent parts, extract and modularize, port, verify.

Except…

There were no requirements. And there was no version control implemented (unless you consider dated, initialed comments version control–hint: it’s not). But worst of all, another software engineer with the best of intentions decided that the legacy code was poorly organized and needed to be completely rearchitected.

First, he was right. Those hardware-dependent parts: everywhere. No modularity. And what modularity there was depended heavily on Ctrl-C/Ctrl-V: copy and paste running rampant. If good code is DRY (Don’t Repeat Yourself–hint: it is), this code was a fire hose trained on the Pacific Ocean. Global variables ruled the day. Comments were needed because object naming was nigh unintelligible. But the existing comments–when not used as a poor substitute for version control–were not kept up to date, so they did more harm than good. (Pro-tip: please stop bothering with comments unless you’re writing in assembly; I want to read your code not your comments.)

But second, he was dead wrong. Remember, no requirements. The code base had no associated functional or unit tests. The whole system only had an end-of-line test plan. The legacy machine was the design documentation, and the fact that customers liked it and wanted the revision to act the same was the pass/fail criterion.

You are not–repeat not–allowed to refactor code in this situation.

You don’t know the impacts. You can’t test the changes. You have no idea what you just broke. This is a stopgap project to keep the assembly line going until the next gen is released. This is not your Mona Lisa or Empire State Building or Saturn V.

There is one course of action: Click Compile. Fix hardware- or toolchain-related syntax error. Repeat.

The end result isn’t pretty and it’s not maintainable. But neither was the starting point. Step away from the editor (i.e. vi), the schematic/layout suite, the solid modeling tool, the #2 pencil, the screwdriver…whatever. The goal is to ship an almost exact copy. It doesn’t have to be pretty; your customer doesn’t care. It has to ship on time and on budget (your customer definitely cares about this).

All that being said, though, please don’t run your development this way. Don’t get into this situation. Write requirements and tests. Get early buy-in. Use automated testing for software–it’s just more software–so you can refactor and optimize to your heart’s content. Documentation costs money, sure. Useful documentation anyway, and it saves more than it costs.

Know where you’re going before you start walking, and you’ll have a maintainable, efficient system that will be more profitable in the long run.

• Rebuilt Engine

Fri 15 March 2013 - 11:33:09 CDT

The marathon coding sessions are done; 35 productive hours over three days. I deleted a bunch of code and made this blog more maintainable.

Writing the original blog engine in Rails was a great case study, but at the end of the day, there are plenty of things out there that handle blogging and have much more mature editors than my initial crack at it.

In short, inspired by Thoughtbot’s Tools of the Trade and Seth Godin’s bullet point about leveraging cheap off the shelf software, I dropped the Rails ActiveRecord model for the blog and instead hooked into Tumblr’s API. (Tying into an external API was another good exercise for upcoming projects.)

The end result is that you should be getting more posts from me and more often. And this also gives me solid base from which to launch my podcast.

Stay tuned.

• MD5

Mon 23 July 2012 - 16:07:00 CDT

#software

I thought we were pretty much past corrupted downloads at this point in the century, but apparently not.

I’ve been doing some software work recently, and I needed to download a demo compiler. The download completed, and I started the install, but it never finished. It turns out that the install crashed because it had managed to fill up the 20GB of free space in my Windows virtual machine. And that happened because the installer file was incomplete and it went off into the weeds.

Three download attempts and two hours later using a total of two OSs and three different browsers, I finally got the complete file. (Especially disappointing given that the full version of this compiler is rather expensive.)

So Pro Tip: always at least check file sizes. Also on OSX you can calculate the MD5 checksum of a file from the terminal using:

\$ md5 myfile


On Windows, there are several free utilities a Google search away.

• En?t[oy]mology

Mon 16 July 2012 - 20:45:00 CDT

#software

Driving home today, I was listening to a podcast discussing beekeeping and the strange disappearance of bees. They mentioned the Latin names of some desirable (to bees) flowers and also of the bees themselves.

I had to wonder if anyone out there studies the origins of names of insects. Would that person be an entomologist, etymologist, or both?

(Oh, the title: if you need a good online resource for learning about or testing regular expressions, check out http://rubular.com.)