Don’t Do It Yourself

"Do It Yourself" or "DIY" for short is a popular way to save money and get things done quicker at home. While few people remodel entire kitchens by DIY, I know I'm not the only one who regularly repairs faucets, or even assembles simple furniture.

But at work, DIY can turn out to be equivalent to another well-known "D" expression: Don't Reinvent the Wheel.

I recently returned to a bit of C programming, in order to familiarize myself with the daily challenges of developers I want to help and support. Developers who remain in C due to embedded platform constraints. I figured that if I wanted to offer this or that tool as a solution to some problem, I'd better try it myself first.

Getting back to C programming meant I needed two things: some source code and a compiler. I found some code I'd written a while back in C++, and decided to rewrite it in C. As for a compiler, why not cl – the command-line compiler from Visual Studio 2005? Not the key part of that comprehensive Microsoft product, but I figured it would do. And of course the Visual Studio editor looked fine too — I could use it to browse my code even if I didn't bother to remember how to set up an entire Visual Studio project.

Merrily I started on my way. Review my old C++ program. Relearn what isn't in C as opposed to C++. Redesign. Write function prototypes in an .h file with some stubs in the .c file. And … compile!

Lots of errors!

No big deal I thought. Just stare at the code, change something, go back to DOS, compile, pipe the error results into a text file, review them, try again. Tiring, and it didn't work.

Rule #1 is hard to follow, but usually helps: leave it 'til tomorrow when you're better rested. All that switching back and forth between windows was tiring. And frustrating when the errors refused to go away.

Next day, by coincidence, a co-worker gave me a copy of a professional source code browser called Source Insight, which he had shown me several months ago. I returned to my task, and was faced with a choice. Go back to looking for the cause of my errors, or take time out to install this new "toy". (Actually, I had known from the first time I had seen it that it was much more than a "toy", but I had never really tried it.)

I installed it. I learned that one could define one's own "compile" command and install it on the menus. Even that it could be told to parse the compiler output and hyperlink between it and the source code. It took me a good hour, especially without documentation for Microsoft's environment variables batch file required for cl to work. But I slowly remembered DOS batch file language, and got it working.

I compiled again, this time with a professional tool. The errors came up, each hyperlinked to the source code. I looked at the first error message, flipping back and forth between it and the source code. I looked up the error C2143 via Google, and got to Microsoft's succinct explanation. Didn't help much.

I stared at the line of code again. This time, though, each element in the line was marked in a different color according to its role in the statement. (Yes, Visual Studio does some color-coding, but Source Insight does much more.) After about two seconds I saw that what I had written was ridiculous: I had used const in place of a #define but had forgotten to use an equals sign to make the assignment.

I fixed it and the error went away.

I had known that Source Insight existed. I had known where to get a copy: from someone who had invested time in identifying an excellent source code browser and editor. But I had tried the wrong kind of DIY — reinventing the wheel — instead of just going and asking for one.

In such cases, don't do it yourself.

Advertisement

Good Code is Specific

I caught myself gazing at the cover of Robert L. Glass' updated edition, Software Conflict 2.0: The Art and Science of Software Engineering. (Reviewers say that the book is good and thought-provoking. It is, though I don't know if anyone meant even the cover.) What's on the cover is an off-center photograph of a code listing. I doubt he actually expected anyone to read the code. But I did. With all due credit to Glass, the sample reads, in part:

if(find_func(token)) { /*rich …
call();
[…]
}
else *value = find_v …
get_token();

etc.

Judging by the one specific word — "token" — in the code snippet, it's probably part of a parser or compiler of some sort. Or a generic sample written to look that way. But that's just the point: most of the code in software books we expect to learn from is generic. The variable names are bland and neutral, presumably in order to make the example as general as possible.

This is a problem, because real code is specific.

Any software that, to use a popular expression, "adds value", does so precisely because the developer wrote specific functionality to solve someone's problem today.

Wouldn't you expect the source code for such software to reflect that goal?

Digression. Consider furniture. I often do because, at least in our neighborhood, every street seems to have a least one dumpster filling up with out-of-fashion kitchen cabinets and bathroom fixtures. The old making way for the new. It's the age of renovations!

When I was growing up, furniture was solid wood, and purchased as individual pieces chosen for beauty and purpose. As I child, I understood that you had to be very well off to buy custom-made furniture. The rest of us took what was in the store window.

Now things are different. I watch my wife choose the new bathroom sink cabinet, or closet for the kids' bedroom. Modern furniture is made out of malleable components (plywood veneer) cut to fit the exact shape and layout of that small corner of the room where we can fit furniture and still be able to walk around the room.

As I looked at the new cabinet, with its outline following the corner of the wall, and its cookie-cutter back with an opening for otherwise hidden water piping, I realized that I had never learned to build a cabinet like that. Specific. Non-rectangular. Adjusted to fit.

We also went shopping for a new couch (after 10 years of a fine couch that the dog thought we'd chosen to be his bed). There too I got an education. A good couch is custom-built as well: choices of material, thickness and angle of the back, shape of the feet.

Real furniture is specific. Even if it doesn't look custom-built, it is.

I didn't learn that in shop class. We learned how to make square tables, rectangular bird houses. The most complex project maybe was a chess board. Lots of little squares fit into a square frame. After that, I copied what I saw in catalogs, using the same generic patterns. This training did not make me into a professional furniture-maker. Not at all.

Back to software. A lot of code looks like my chessboard. Neat. Functional. Lots of generic variable and function names like "ret_val" and "MessageHandler". Suprisingly hard to understand and maintain, though, because there's little clue, from reading the code, about what the software is supposed to do.

What's the solution? I'm not sure. I know what the end result looks like: code that contains meaningful, specific names. Like "ParseSubjectField" in a spam filter, or "BoilOverTemperature" in a nuclear reactor system.

Maybe a good start is:

• Use meaningful, that is to say, specific, names for things in your code
• Read other people's real code and, where you don't understand, ask, and suggest specific names
• Find a good carpenter and follow him (or her) around

Good is Better than Quality

Many have either written about the power of meanings (e.g. Orwell’s “newspeak”) or manipulated them (e.g. Lenin having called his then-minority party “Bolsheviks” — the majority). Since this blog is about quality, I guess I have to say something about “quality”. There too, greater minds than I have gone. Pirsig’s Zen and the Art of Motorcycle Maintenance is famous and a good read.

But looking anew at current usage in various fields, one thing stands out: almost nobody uses the chief dictionary definitions — character, feature, essential attribute. Yes, the popular meaning is there too. Merriam-Webster lists “superiority in kind” as definition 2b for “quality” with an example, “merchandise of quality“. Of course, M-W is right in listing it, because a good dictionary is comprehensive.

Well! There’s the word I would use instead right there! “Good”.

When people start talking about “quality products” any shared vision between the speaker and the listener begins to get fuzzy. What is “quality”? Less variation? Fit for use? Zero defects? Meets requirements? Satisfies the customer? Suddenly, anything goes.

An attempt at fixing things is saying, “No, no, let’s say what we really mean: good quality.” (As if anyone would have a long discussion about “bad quality”.)

It’s so much simpler, though, to just drop “quality” and say “good” when we mean good.

In every field, people know good when they see it. Nobody argues about it. It certainly doesn’t get to people claiming that “good” is “bad”. “Good” is good.

That’s why good is better than quality.

Books as a Means of Communication

Yesterday, for the first time in a long time, I had a chance to work with someone who had recently read the same book that I had. We happened to be talking about different categories of tools. It was a great session — we got a lot done.

What is a book itself a tool for? And how is it a means of communication?

The answer seems obvious: a book is an author’s way of communicating with a large audience. But the obvious answer is mostly wrong. While there is a one way “broadcast” in a widely-published book, that’s not the major benefit, and it’s certainly not two-way communication. Rarely do readers get to speak with book authors.

For writers, a book is often a way to get thoughts out of one’s head and out on paper so one can think again. And, if it’s a great book, a chance to enjoy creating a work of art as well.

But for readers, the book is a tool. It is an application-specific language for conversations in the book’s field or topic. If you’ve ever had trouble getting to the point in a discussion because it takes so much time to set the stage, a book is missing. Complex subjects are best addressed first in writing. If both participants read a book, they can use the concepts that the author has spent months or years defining and refining, and start their conversation on the same wavelength.

Want to jump-start productive conversations? Read a good book.

Explain it to a Computer

For most people, “talking to a computer” conjures up scenes of being trapped in a low-budget retailer’s voice mail system. But today I was reminded of when it can be helpful to talk to a computer, or specifically, to explain something to a computer.

I saw a great demonstration today of an automated test system for on-screen TV guide software. We got to try it out in a hands-on tutorial. I learned the most, though, from just one question and answer.

We were using a screen capture feature with text recognition to set up a test of whether the right words appeared at the top of a menu on screen. All visual, drag-and-drop design. You draw a rectangle on the screen around the area whose text you want to check.

Question
How do I know how much blank space to include around the text for capture? Makes sense to just mark the text, but maybe I should mark more? What if the right text appears, but aligned on the other side of the screen? Is that an error, or not?

Answer
Automated testing is very black and white. In the middle of the night, the test will either pass or fail. If you’re not sure what should be considered an error and what not an error, talk to the person who wrote the requirement. Maybe s/he didn’t think of the question either, but will now.

I always thought of automated testing, even with its setup costs, as a way to save time, avoid boring, repetitious work, build in self-test, and run reliable regression testing.

But the real benefit may be in its power to clarify requirements. Put a computer on your test team and it will ask all sorts of detail questions that a human reviewer didn’t think of.

Choose and Use the Right Tools

I just finished a simple carpentry job: drilling a 4 cm hole through a 6 cm desk for a connector on the end of a PC video cable to go through. My 16-year old son worked with me, and made any number of helpful comments to save us making errors. We avoided most of those errors thanks to him. Part of the story is that risk identification isn’t enough — there has to be risk analysis (likelihood and expected cost), risk prevention planning (pre-plan for how to avoid the risk becoming a reality) and mitigation planning (pre-planning what we will do if the risk does become a reality). And estimate the cost of fixing as feedback a recheck on the original cost in the risk analysis. Needless to say, I didn’t complete all steps for all risks, and some damages did occur. I made an arc-shaped scratch on the top surface of the desk, and a piece of bottom surface wood detached under the desk. There are many steps in risk analysis and people often check it off as done after doing just the risk identification.

But that wasn’t really the point of the story. The point of the story is related to one of the risks my son identified: “Dad, the circular saw is not deep enough to cut through the entire desk thickness.” I responded, “Good point — I’ll have to complete the circular cut from the bottom after doing most of it from the top. At least the saw is deeper than half the desk, so it should work out.” But after a successful half-cutting from the top, when I went under the desk I realized the significance of something else my son had pointed out. He had said, “Dad, the circular frame for the circular saw is a larger diameter. You won’t be able to cut from the bottom because you’ll hit the drawer frame under there.” For that risk I also had an answer: “OK, I’ll do the entire cut from the top.” (More about risk analysis: mitigation plans must all be cross-checked to make sure none contradict.)

Realizing that I wouldn’t be able to complete the job from under the desk, I went back to the top of the desk and figured (totally illogically — just emotions here) I might as well cut as deep as the saw will let me go, and then figure out what to do next. Fine — I got another 3 mm and then the circular frame for the circular saw made contact with the smooth desk surface and made that arc-shaped scratch. My son was not happy, but he forgave me.

But here’s the point. The right response to the “saw isn’t deep enough to cut through the desk” would have been simply, stop, go to the store with the saw as example and the desk measurement, and buy a deeper blade or circular saw set. Then come back and do the job with the right tool.

But since it was Independence Day and (I assumed that) the stores were closed, I forged on using a set of hand chisels. Fun enough. Nostalgic for the days of my youth when carpentry was without power tools. I did succeed. Took an hour instead of 2 minutes. The hole is correct and smooth but not as close to perfect as if done with a circular saw. And yes, the chiseling is what detached the piece of wood from the bottom surface of the desk, though circular saws can do that too if you’re not careful.