What Did You Break?

Greg Ingersoll

Tue 03 September 2013 - 14:11:10 CDT

#system_engineering #requirements #software

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.


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.

comments powered by Disqus

Get Updates

Subscribe to the blog to get automatic update. And post comments or contact us for more information.