Talk About Quality

Tom Harris

Good Code is Specific

with one comment

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 …
else *value = find_v …


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

Written by Tom Harris

May 23, 2006 at 8:07 am

Posted in Code Quality

One Response

Subscribe to comments with RSS.

  1. Hi there, this is Daniel Read from developer.* Books, publisher of Software Conflict 2.0. I happened across your blog post while checking up on references to the book in the Google search results. I enjoyed reading your post.

    I wanted to clarify just for the record that the code on the front cover was chosen only for it’s visual qualities; no other figurative meaning is implied, though I like the thought directions you pursued in response. If I remember correctly the designer of the book cover, who is not a programmer, found that code snippet somewhere. 🙂

    Regarding your comments about code specificity and the danger of too much generality, one thought I had was that layering is a common way to manage this issue in my designs. I start out with the most generic types of functionlity at the lowest layers, and get more specific at the upper layers, with the presentation layer and “business objects” typically being where domain-specific specificity would be immediately recognizable.

    All the best,

    Daniel Read

    June 30, 2006 at 10:38 pm

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s