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).