From oscar at iam.unibe.ch Thu Nov 6 11:40:50 2008 From: oscar at iam.unibe.ch (Oscar Nierstrasz) Date: Thu, 6 Nov 2008 11:40:50 +0100 Subject: [sbe-discussion] Re: book feedback In-Reply-To: <0F721954-C2C1-4C68-87CB-0F4F22637581@ociweb.com> References: <0F721954-C2C1-4C68-87CB-0F4F22637581@ociweb.com> Message-ID: <00E878B2-4C73-4B6E-AA64-CF3AF712E155@iam.unibe.ch> Hi Mark, Thanks a lot for your feedback. We have all been a bit busy, so no one has had a chance to look more closely at your comments till now. On Oct 14, 2008, at 18:19, Mark Volkmann wrote: > I love this book! I bought a printed copy from LuLu and am very > happy with the quality of the printing and the binding. > > I've read up to page 162 so far. Here is some feedback. > > section 1.4 (page 11) - "can resize windows either by dragging one > of the corners ..." > In the image I'm using (squeak-dev), you can also resize windows by > dragging edges. Hm. This is not so in the one-click image we are using, so I will leave that as is. > section 1.10 (page 22) - Method 1.1 > The parentheses aren't needed. Sure, but sometimes parentheses are nice for the human reader. > section 1.11 (page 27) - "The most important of these are ..." > I suggest adding "browse it (CMD-b)". Absolutely! Fixed. > section 2.7 (page 41) - "and then answers the new value." > It's not clear to me why setter methods should do this. I suggest > adding an explanation. Well, the explanation would simply be something like: "Setters return the new value so that it can then be used as part of a complex expression." I think such an explanation would just generate unnecessary noise. > section 3.1 (page 54) > This briefly discusses "primitives". I'd like to see a little more > detail. Are these always implemented in C? Are these always things > that just can't be implemented in Smalltalk? Can there every be a > situation where I'd want to call them directly from my code? It is certainly interesting, but goes far beyond the scope of this chapter. Maybe this is something for SBE 2. > section 5.3 (page 84) > This gives three examples of protocol names. I'd like to see more. Already introduced in 2.7. Many protocols have already been seen by now. > section 5.3 (page 87) - method 5.3 > This includes the code "count := count + 1" which raises a couple of > questions for me. > Why isn't there a ++ or increment method? > Are Integer objects immutable? Well, in the syntax chapter we see that operators are binary. There are no postfix operators in Smalltalk. It's true that we do not really discuss immutability in the book. We try to emphasize the high level view rather than the technical differences between primitive objects like integers and "real" objects. > section 5.6 (page 97) - "Return a value only when you intend for the > sender to use the value." > What if you just want to exit a method early? Shouldn't "^self" be > used for that even though the caller probably won't use the return > value? Sure. Good point, but the exceptions always make rules less elegant to express. > section 5.7 (page 103) - "Sometimes we need to share some data > amongst all the instance of a class and the class itself." > I suggest adding to the end of this "and subclasses". It is stated at the top of the next page. Should be clear enough. > section 6.2 (page 114) - Change "focussed" to "focused"? > It looks like both are acceptable, but the latter is preferred. Not "prefered"? ;-) > This occurs somewhere else as well, but I can't find it now. I checked. There are four instances in the book, and they are spelled consistently. Either spelling is ok in English. > page 122 on "Refactoring" - The OmniBrowser doesn't have the "R" > button. Yes, we assume the one-click SBE image. However the footnote should make this clear. > page 123 on "Browsing programmatically" - "a number of utility method" > should be "a number of utility methods". Fixed. > page 124 - There are three SystemNavigation code examples. > Why do the first and third end with ": ."? > Why do any of them end with a period? Actually all three do. No special reason, but this makes it easier to chain them all together. > section 6.5 (page 138) - "Incidentally, if you want to open an full > inspector ..." > Change "an" to "a". Fixed. > section 6.9 (page 148) - "general-purpose tool from browsing ..." > Change "from" to "for". Bizarre! Fixed. > section 6.9 (page 150) - "each of the top four panes ..." > Change "four" to "three". Nope. It works in all four panes (including the topmost pane). I just checked. Thanks a lot for your comments, and taking the trouble to document everything. Cheers, Oscar Nierstrasz From oscar at iam.unibe.ch Thu Nov 6 12:29:04 2008 From: oscar at iam.unibe.ch (Oscar Nierstrasz) Date: Thu, 6 Nov 2008 12:29:04 +0100 Subject: [sbe-discussion] Re: book feedback - part 2 In-Reply-To: References: Message-ID: <0F9F2EBE-EE7B-4D3C-9F06-62C62F63541C@iam.unibe.ch> Hi Mark, Thanks for this second batch of comments. Sorry we did not have time to get around them until now. On Oct 19, 2008, at 20:56, Mark Volkmann wrote: > I finished reading the book and want to provide feedback on pages > 163 to the end. Refer to my earlier post for feedback on the first > 162 pages. > > section 8.1 (page 176) - "The default implementation simply write > the class name ..." > should be "The default implementation simply writes the class > name ..." Already fixed in version 2008-05-15 (see errata of 2008-06-05). https://www.iam.unibe.ch/scg/svn_repos/SqueakByExample/Book/errata.txt > section 8.1 (page 177) - discussion about "self-evaluating > representation" > It's not clear why I should care whether an object is self- > evaluating. How is it relevant to the code I'm writing? If you have complex objects, it can be very handy to have them generate printable representations which are just Smalltalk expressions that can be evaluated to regenerate the same object. You can use such expressions in tests, for example. > section 8.1 (page 182) - In the section on "Debugging", consider > adding a 1 footnote reference to the first sentence of the second > paragraph. This same paragraph says "Otherwise an exception will be > raised." I suggestion specifying which kind is raised. Right. Fixed. > section 9.5 (page 210) - "When the method do: is sent ..." should be > "When the message do: is sent ..." Ouch! I thought I fixed all of those already. Fixed now. > section 10.3 (page 221) - "until it finds an element equals to its > parameter" should be > "until it finds an element equal to its parameter" Fixed. > section 10.3 (page 224) - In the code example in the "About > Concatenation" section "(ms)" is used in one place and > "(milliseconds)" is used in another. Make it consistent. Fixed. > section 10.4 (page 228) - What's the difference between fileNamed: > and oldFileNamed:? The description of oldFileNamed: says "If the > file already exists ..." implying that it doesn't have to exist. Good question. I do not immediately see the answer from the source code. Damien, can you help? The descriptions of the two methods do not really make the difference clear. > section 10.4 (page 229) - Explain what kind of file is represented > by a file with a .pgm extension. Apparently it is the "portable graymap file format" -- http://en.wikipedia.org/wiki/Portable_pixmap Fixed. > section 11.1 (page 232) - "s openViewerForArgument" What argument? Right. The method should be called "openViewerForReceiver". > section 11.5 (page 239) - Change "mouseUp" to "mouseUp:". Fixed. > section 11.5 (page 240) - What's the purpose of drawOn:? Is it to > repaint a morph? Yes. > section 11.7 (page 245) - Explain the purpose of > addDeferredUIMessage:. The text says "Here we tell the \ct{World} that the hand should grab \ct{self}, the rejected morph." I think more detail would be overkill. > section 11.8 (page 249) - "to show quickly all the faces" should be > "to quickly show all the faces". No, that would introduce a split infinitive, and Andrew would be upset ;-). > chapter 11 - general comment - Why were morphs for basic things like > labels, text fields, buttons, checkboxes and lists not even > mentioned? This omission makes Morphic seem like a toy instead of > something to be used for building UIs for typical applications. Yes, a more practical example would be better. Point well taken. We were lazy and adapted an existing article in french, whereas we should have written something new. Should be done in SBE 2. > section 12.5 (page 262 and 265) - Add ProtoObject to figure 12.7, > 12.8, 12.9 and 12.10. We deliberately left it out. It is a relatively obscure implementation issue. > section 12.5 (page 263) - "(i.e., representation and number)" Should > "number" be replaced by "count"? To my ears, "number" is clearer than "count". > FAQ 9 - Clarify that "new methods" means methods that are not only > defined by a superclass (can be methods only defined in the current > class or methods that the current class overrides). Fixed. > FAQ 16 - What does "chf" stand for? Swiss francs, of course ;-) Thanks again for all your detailed comments! - on > Once again I'll say I think this is a great book! Perhaps the > biggest omission is that it doesn't discuss what to do after you're > written an application. How to you make it available to users that > aren't Squeak developers? How do users launch it? > > --- > Mark Volkmann > > > > > _______________________________________________ > Sbe-discussion mailing list > Sbe-discussion at iam.unibe.ch > https://www.iam.unibe.ch/mailman/listinfo/sbe-discussion