Rock, Paper, Scissors–oh Sh#$%!

What’s your reaction to errors in a technical book or article? If you are like me, you discount the writer’s words if there are too many errors. If I find the topic interesting, however, I ignore infrequent errors and plunge ahead. But sometimes errors impede understanding. In that case, it’s always good to ask what the author meant to say. From time to time I get emails from readers tripping over errors in my own books. I try to thoughtfully answer their questions. Let me share a recent query:

Hi Rebecca,

I’m a little confused with your paper, rock, scissors example and the errata for your Object Design book. I figured out there seemed to be a problem when I got to figure 1-9. I went looking for errata. But the errata seem to have a problem too! For page 21, it mentions figure 1-9, but figure 1-8 is on pg 21! I’m not sure whether the page number is wrong, or the figure…. I’m assuming the figure. But beyond all that, I don’t understand the purpose for three added methods beatsRock(), beatsPaper(), and beatsScissors(). Since a rock only calls beatsRock() and a paper only calls beatsPaper(), then why do we need three methods in this interface? Why not just have a “beatsMe()” method that is defined for the particular class being defined? Any clarification would be appreciated.

This reader had every reason to be puzzled. Not only did the example in my design book have a coding error, but the accompanying sequence diagrams did too. Even more frustrating, the errata referenced the wrong figure. After acknowledging the reader’s concerns, I went on to explain at some length that the purpose of this rather contrived example was to illustrate how double dispatching works. While indeed, the answer could’ve been implemented in a single method, that wasn’t the point. Instead it was to illustrate that double dispatching eliminated the need for case or switch statements. Double dispatching (whether you think it is a good idea or not) is a tricky enough to grasp even without the typos!

I didn’t intend to purposefully introduce errors. They crept in because writing and editing, like coding, require concentration and attention to detail. Because I’m human, I’m not perfect at tasks like these. Most people aren’t. With material that you are overly familiar with, you tend to read into it what you meant to say, skipping over small mistakes without even seeing them. One way I’ve found to force my brain to look at text or code with a fresh eye is to read it from the bottom up, one sentence or expression at a time. This shifts my perspective, allowing me to see errors more readily.

When others revise your work, there are even more opportunities for introducing error. Overzealous copyeditors introduce errors because they don’t believe you would want to say something that way (you couldn’t have meant OffF(i), so I’ll just change this to Off(i). Never mind that OffF(i)—for Off-Floor—was exactly what you intended). I understand why some insist on typesetting their own books and compiling every line of code. An author has to be really on her toes to catch those “thoughtfully” induced errors. These can be especially difficult to detect because our brains skip over infrequent mistakes, especially when we “know” what is right. Fortunately, the more errors there are, the easier they are to spot. But first the fact that they exist has to be brought to your attention.

Ever wonder why pair programming is advocated by Extreme Programmers? It’s not because geeky software types as a general rule like to socialize, but because one can spot another’s mental lapses. Ever wonder why test-driven development is catching on? Tests force you to think through the functionality you want to implement with a fresh viewpoint, catching errors in your thinking before you code.

The next time you spot an error in a book or an article, consider letting the author know about it. I know I would appreciate hearing from you. Your comments make me a better writer (and you a more actively engaged reader).

Problem Frames and an Eager Designer

The past few weeks I have been participating in a book study group on Michael Jackson’s Problem Frames: Analyzing and structuring software development problems. Problem frames are a concept that Michael Jackson (the UK software analyst, not the courtroom celebrity) invented to characterize classes of problems that computer programs solve. According to Jackson,

“A problem frame defines the shape of a problem by capturing the characteristics and interconnections of the parts of the world it is concerned with, and the concerns and difficulties that are likely to arise. So problem frames help you to focus on the problem, instead of drifting into inventing solutions.”

Problem frames are lenses you apply to look more deeply at a problem. If you know what type of problem you are looking at, you can ask intelligent questions and make tighter specifications for how your software should behave and how it should interact with things in the world. Being a designer, I’m always looking to solve problems. Yet it is true that mixing up problems with solutions can cause interesting communication problems and disconnects.

Consider this statement from a Canadian farmer about the trouble with daylight saving time: “Chickens do not adapt to the changed clock until several weeks have gone by so the first week of April and the last week of October are very frustrating for us.” OK, I’ve gotta ask, do chickens really understand changed clocks? Of course not. The problem isn’t that chickens can’t adjust to the changed clock. The problem is that farmers’ sleeping and waking habits shift as a consequence of daylight saving time. The chickens still are disrupted, but only because the farmers have adjusted their behavior. Let’s not mix up cause with effect.

Jackson’s book is full of examples that exercise the muscles in your brain that help you untangle cause from effect and explore how much of the real world you have to understand before you can specify how your software should behave. It has been novel for me to take several steps back in order to deeply understand the nature of a problem. Be aware that I have a healthy skepticism for “big upfront analysis” just like I do for “big upfront design”. I don’t think the right approach for me is to spend lots of time deeply pondering problems before I start thinking about solutions. But l hope to apply Jackson’s ideas and deep insights on problems into practical advice and recommendations for those who aren’t keen on formalisms. Stay tuned.