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.
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.
Sun 24 March 2013 - 18:19:50 CDT
So it’s the time of year when I spend some—ok, maybe a bit too much—time watching some interesting sports. My Wisconsin Badgers in basketball who did well in the B1G tournament but not the NCAA; the Badgers in hockey who won the WCHA tournament and are off to the NCAA; and the start of the Formula1 racing season where I’m intrigued by the personalities, and I love the technology.
But I question the advertising.
Watching the Malaysian Grand Prix this weekend, there was a common ad for a motorcycle/ATV company who were touting their “driver-centered design.” Now this may be novel because their competition ignores the driver or their own previous designs did. I’m not sure. But why would anyone designing a motorcycle not center the design on the driver? The driver is fairly important in the equation. (And before you mention aerodynamics, don’t forget that a fast bike is something the driver wants.)
The same is true for any user of any product, and you need to pay attention when capturing requirements and working through the initial design and engineering of your next product. Starting with the user allows you to form a logical tree of requirements that are all rooted in things that provide value to your users or address their concerns or give them enjoyment.
Now, user requirements are certainly top-level requirements, but they are not the only things on the top line. Certainly if users don’t want your widget, you won’t sell very many. But if governments won’t let you sell it, you won’t sell very many either. You also need to consider agency requirements and fulfillment of standards—for the FCC, FDA, USDA, UL, CSA, CE, and on and on—from the start. (I’ve seen too many people try to fill out a mountain of paperwork at the end when things are already running late and running out of money.)
Finally, there is your brand. In order to compete, you need to differentiate your product from the other guy, and often the products you offer will have similar features and traits. Ask your marketing experts for specific guidelines for colors, sizes, logos, icons, labels, etc. at the start of your next project. Don’t wait until they see the prototype and ask you to change, well, everything.
So to get off on the right foot, build your top-level requirements with three categories in mind:
…and branch out from there.
Mon 11 March 2013 - 14:10:00 CDT
I was reviewing customer requirements on a recent project, and we came across something unintentionally comical. There was a requirement for illumination intensity which is given as power per unit area, in this case microwatts per square centimeter (uW/cm^2). The problem was that the m was missing leaving uW/c^2.
Now c is not a unit, but in the context of light, it represents the speed of light with units of meters per second. Just for fun, I plugged this into Wolfram Alpha as “500uW/c^2”. This reduced to having units of kilograms per second which the tool interpreted as “recommended dietary intake”!
This instance was an obvious typo, but it does highlight the need to be careful when authoring and reviewing requirements. Missing a digit, for example, could have far-reaching consequences for your project. And completely wrong units can cause your Mars probe to crash. Better to catch these things early.
And while we‘re on the subject, what do you use for requirements management? I’m guessing Word/Excel is a popular answer. Leave a comment below. This is a topic I will be covering in future posts.
Mon 04 March 2013 - 12:48:00 CST
I’ve been keeping this link around for a while because the first one on the list actually happened to me in the Detroit airport. Well, something very similar. I had a flight leaving soon, wanted coffee, but can’t drink it—especially quickly—when it’s too hot. So I asked the barista to put some ice in the cup to which she replied, “Do you want the ice at the bottom or the top?”
I had no idea how to respond to this except to think to myself, “If you can keep the ice at the bottom, that would be a neat trick.”
At any rate, it is a short, interesting article that reveals a bit about what all scientists, engineers, and product designers are up against sometimes. Remember these when you are:
And contact us if you need another set of eyes on your requirements, need people to help with your STEM initiative, or if you have an idea for something you would like to learn from this blog.