rc3.org

Strong opinions, weakly held

Making computer books more usable

The book Programming Ruby, also commonly referred to as “the pickaxe book,” is widely regarded in the Ruby community as a must-have. Unfortunately, it doesn’t really meet my expectations. You can find parts of the book online, so you can see for yourself what I’m talking about.

Take a look at the chapter on Basic Input and Output. Let’s say you want to open a new text file and direct your output to that file. This seems pretty basic, and you’d expect to see it explained in a chapter that purports to cover input and output. On this seemingly important topic, readers are given one sentence and no examples:

The same methods that we’ve been using for “simple” I/O are available for all file objects.

Perhaps I am an atypical computer book consumer. If I’m in a hurry to get something done (and I’m always in a hurry), I find the right chapter in the book and skim the code samples to find one that illustrates how to do what I want to do, then I read the surrounding text. I’m not interested in reading the full chapter and drawing inferences, especially in cases like this where I know how to accomplish the same task in about ten other programming languages and I just need to know the syntax. Anyway, here’s the missing example:

f = File.open(“mynewfile.txt”, “w”) f.puts(“a line of text”) f.close

How difficult was that?

5 Comments

  1. That actually makes your point better than you may have realized… something like

    File.open("mynewfile.txt", "w") do |f|
    f.puts("a line of text")
    end
    

    is rather more idiomatic. (It also arranges for the close to happen even if something in the middle throws an exception).

  2. O’Reilly’s cookbooks (at least the Perl and Java Cookboks) are fantastic for this sort of thing. Is someone slaving on a Ruby Cookbook?

  3. FWIW the online version is the old edition of the book. Here is what the 2nd Edition has to say on the subject:

    As you may expect, you can create a new file object using File.new.
    file = File.new("testfile", "r")
    # ... process the file
    file.close
    You can create a File object that is open for reading, writing, or both, according to the mode string. (Here we opened testfile for reading with an “r”. We could also have used “w” for write or “rw” for read-write. The full list of allowed modes appears on page 504.)

    etc.

Leave a Reply

Your email address will not be published.

*

© 2016 rc3.org

Theme by Anders NorenUp ↑