[ruby-talk:8141] Re: Code examples in the pickaxe book [long]

Dave Thomas wrote:
 
> A couple of people have mentioned here that they're having problems
> because they're typing in code from the book, and some of the code
> fragments aren't self contained.

Which likely means that *many* (say, 10x-40x ) more people are having 
similar sorts of problems, but are otherwise too reluctant to advertise it 
to the rest of the world. For most people, it's often much easier to learn 
things if all sources of otherwise distracting and bandwidth draining 
ambiguity are removed.  This is probably even more important here, since 
many people will be new to Ruby *and* OOP, yet the order of presentation 
is somewhat oriented to (or somewhat optimized for) those who *already* 
have a significant OOP background. And this is also a factor to consider 
for those for whom English is not their native language. 

> I need some help from folks on the list to decide what to do. 

If you want to maximize world-wide Ruby use and understanding, I don't 
think you should let the opinions of the (comparatively) super-expert 
(OO)P people who like to puzzle things out over-ride the 
probably/potentially (say, 10x-40x) larger number of (comparatively) 
non-expert (OO)P people who just want to learn and use Ruby without 
unnecessary added challenges (at least to start with). We (presumably) all 
want Ruby to earn a reputation as a powerful but easy to learn OOP 
language--which means that you should relentlessly and conscientiously 
cater to the great majority of mainstream users (without neglecting the 
leading edge elite).

> I'd like
> to publish the source code, but there is a problem, and I don't know
> how big it is.
[...]
> Each line starts with a '!' followed by a flag character. These lines
> are interpreted by a preprocesor. So, for example, when we include the
> code for page 27 in the book, we say
> 
>    \begin{ruby}[0,1,8]
> 
> and in the typeset bok you only see the lines flagged 0, 1, or 8.
> 
> The benefit here is that the book code is shorter, and more relevant
> to the point at hand. Another indirect benefit is that the code is
> consistent: the method 'Song.initialize' for example, is defined once,
> and then included where needed throughout the book.
> 
> But here's my problem. Take the code on page 25. There we talk about
> writable attributes, and show the definition of method 'duration='
> (flagged '5' above). A couple of paragraphs later we save 'but Ruby
> can write this for you' and show attr_writer instead (coincidentally
> flagged with '6' above). The code for the class contains both methods.
> 
> So, if I publish the source of class Song as it really is (the code
> above minus the !'s), you'd end up with _both_ an attr_writer and a
> definition of 'duration=' in the same file. And that's what worries
> me. Folks might get the wrong impression from this, and we'd end up
> confusing things even more.

I think an explanation along these lines is sufficient.

To keep life simple for yourself and your readers, I'd recommend showing 
all the code *only* on your web site, and to show *all* the code for 
*each* example, with the originally printed part in each case being 
background highlighted. (I'm assuming that you can somehow mechanically 
exploit the current extraction mechanism to generate the alternative HTML 
form on the side.)

Conrad Schneiker
(This note is unofficial and subject to improvement without notice.)