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:
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-i—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).
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-i—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).
posted by Rebecca Wirfs-Brock at
3:03 PM
5 Comments:
I once signed a printer's proof of some cover art that I had seen one hundred times. Printing the covers again cost me $800+.
When people remember, they cannot see.
I've never found a solution for over familiarity.
I just checked out your book on Amazon and decided to buy a copy---it looks like it's full of useful ideas, explained clearly. While I was reading the excerpt I noticed a grammatical error. I'm no language purist, but I'm a voracious reader with a keen eye, and whenever I come across any kind of error it breaks the flow and slows me down. And it raises the question "How far can I trust this writer's competence?" (That's "raises the question" not "begs the question" as everyone seems to be saying these days. That one's particularly galling because "begging the question" really means "arguing in a circle", a basic logical fallacy. If everyone knew what it means to "beg the question", maybe they wouldn't do it so much.)
The error is on page 85, where you're discussing whether to model your software's users. You wrote "If it is only their actions that matter and not whom they are, leave them out of the design." And on your errata page you said "The repeated use of 'whom' in the top paragraph seems stuffy. It may be right, but to Alan's ears sounds wrong."
Alan's ears got it right, you need "who", not "whom".
We use "whom" when it's the object of a verb: "Whom do we trust?" In the simple subject-verb-object form, this sentence is "We trust whom?". So let's do the same thing with "whom they are": rearrange it to "they are whom". Now this *looks* like subject-verb-object, but it's not, because "are" is a special case. It's a conjugation of the verb "be". Some others are "am", "is", "was", and "were".
When I say "I trust Rebecca", I say I'm doing something, trusting, and you're the object that my trust is directed towards. But when I say "I am Corcky", I'm not saying that I'm doing anything to Corcky, I'm saying that I'm identical to Corcky. The verb "is" functions like an equals sign: "I = Corcky". And just like Java's "equals" method, "is" works symmetrically. "I am Corcky" means the same as "Corcky am I".
In the sentence "I am Corcky", "Corcky" is not an object---it's called a "complement". Because of the equality of subject and complement, they're in the same grammatical category, called "subjective case".
The phrase "they are whom" is wrong because both pronouns should be in subjective case: "they", not "them", and "who", not "whom". So the sentence we started with should be "If it is only their actions that matter and not who they are...".
That being said, I expect I'll be happy with your book. Most of the errata are like the above: minor errors that won't lead to any confusion. And in a way I actually *like* spotting minor errors---it reassures me that I'm reading carefully enough to really understand what you're saying.
I'm reading Allen Holub's book "Holub on Patterns"---quite a contrast. His grammar is impeccable---in one of his on-line articles he uses the phrase "begs the question" properly, bless his heart. That was one of the reasons I decided to buy his book. But the text is strewn with more significant errors: diagrams that don't match the code, source comments that misdecscribe the code, and particularly egregious for a book on patterns, a definition of Template Method that's just plain wrong. He says a template method is any method that's overridden in a subclass. But the definition in the GoF book says that the template is the method in the superclass that *calls* a series of methods that are meant to be overridden. The template is not overridden.
All in all though, I'm still glad I bought his book. Despite the errors it delivers on his claims---a practical introduction to patterns as they appear in real programs: overlapping and supporting each other.
I'm glad you talk about patterns in your book---I'm sure I'll learn a lot from your views on their place in the design process. Looking forward to reading Object Design!
Corcky
Corcky-
Thanks so much for your comment. I'm grateful for you pointing out grammatical errors and suggesting corrections. If you would be so kind as to continue doing so while you are reading my book, I'd greatly appreciate it. Every time I get a suggested correction I will update and repost an updated errata. Careful reading is much appreciated. Most recently, I've received 2 or 3 corrections from someone who is translating the book into Polish. If you want to send me corrections directly rather than post them to my blog, please feel free to drop me a line at rebecca@wirfs-brock.com
Also, feel free to correspond with me about patterns or any other design ideas that are sparked by reading my book.
Rebecca
Free advice on design from Wirfs-Brock Associates? I'd have to be crazy to say No to that.
I especially liked your description of object role stereotypes. I did a web search looking for further information, but I didn't find much. Do you have any suggestions?
It'll be a while before your book is delivered, but I'll be happy to let you know if I find any other errata.
Corcky
OK, so I'm not the brightest candle on the cake. I just looked at your Resources page: everything I ever wanted to know about object role stereotypes.
Post a Comment
Subscribe to Post Comments [Atom]
<< Home