Available Online: When Print Has No Space for Content

Dr. Dobb’s Journal is a pretty well-known magazine geared towards software engineers, and they’ve been at it for more than thirty years. The articles are generally pretty hit or miss for my taste. I was just reading the August 2008 print edition, specifically Disentangling Concepts in Object-Oriented Systems. It’s pretty meh in my opinion, but that’s neither here nor there. The problem I found is something I’ve come across before in this magazine, but this time it was just plain absurd.

The Setup

The overall gist of the article is the promotion of good OO design. The focus is interface design, and the author begins with an example of acceptable code that could use a little redesign.

I start with a simple implementation of a PolarArray class that meets the requirements previously specified. I fixed the size of the globe to 8×8 (via const variables); see Listing One.

Okay, “Listing One”. I flip the page and there it is, “Listing One”, which is a complete implementation for his example class (plus six lines of example calls). This listing takes up more than half of the page. I am fully aware that this is the stepping stone towards greater understanding. I can see that the author has laid out some perfectly plausible code, in its entirety, as the starting point of a lesson.

Then, predictably, refinements are described. (By the way, all bold text in all of the following quotes are mine).

Consider how you might use the various features of object-oriented design to better differentiate the two concepts in play. What if you refactor the index-translation portion of the class so that it is publicly available? You could force users to understand coordinate system and coordinates as distinct concepts from value lookup.

Listing Two (available online; see “Resource Center,” page 5) certainly differentiates the value lookup from the coordinate system.

Okay, “Listing Two” isn’t included with the article. It appears that the author thought it would be included, because he doesn’t even really describe what he’s done. But whatever. I know that there’s only so much code they’re going to put in a print magazine. The author probably has a few more iterations of improvement to make anyway. And I am curious what the final result will be.

Let’s back up a step and try a different approach….If you add a few enums to the code, the implementation might look like Listing Three (available online). Now we’re getting somewhere!

What?! Alright, there’s no “Listing Three” code either. And seriously, is it just me, or does it seem like the author assumed it would be included with the article? Did the editors at Dobbs do any…editing work on this?

Let’s take this a step further….Similarly, you will create a Pole base class, from which we will derive NorthPole and SouthPole; see Listing Four (available online).

Now we’re really making progress! Looking at the example client code, you see that the distinction between the three concepts—value lookup, coordinate system, and coordinate—is clearly differentiated.

Sweet. What I like to do while reading Dr. Dobbs on the can is to also bring the laptop in with me just in case there’s some code I want to view.

Pay particular attention to the example client code at the bottom of the listing; notice how it is both readable and clearly differentiates the three concepts into separate tokens; see Listing Five (available online).

That’s it. The rest of the show is mostly a recap. Which is what I’d like to do as well.

The Punchline

There were five listings of code, each one serving as a point of improvement against its previous. The only code listing included with this article is the first one, the “wrong” one. It occupies more than half (literally) of the page. It didn’t have to be that way. It’s an interface that’s being described, right? So why not just print the function signatures? We don’t need no stinkin’ function bodies. And example client code? I need to see examples of function calls that have no parameters? With all the space used for that first listing, there’s more that could have been done.

The Kicker

Did you follow my link to the story at their website? You might have already noticed what I find to be the best part of all of this. I expected to see instances of “(available online)” replaced with the actual listings. They’re not. “Listing Two” is followed by “(available online at www.ddj.com/code/)”. The rest just say “(available online)”. That’s it. Not even a friggin’ link.

The magazine’s “Resource Center on page 5″ is a box that mentions “www.ddj.com”. The homepage. I guess they figure you can track down the specific article and from there find the code.

When you have found the article at their website, you are rewarded with “ddr.com/code“? What’s there? A list of three links, each a publications you might have read and for which you might be searching for code.

It’s all so wrong in so many ways. But I feel cleansed having now ranted.