Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • Long code block (Score:2, Informative)

    by clintp (2) on 2002.03.16 16:05 (#6053)
    When I pick up a programming book to purchase, one of my first tests is the flip test. I flip through the book rapidly not really reading but just looking at the content. If I see pages and pages and pages of either endless solid text or code listings I just put it back.

    Programming topics don't lend themselves to long, wordy explanations. There's no point to it. I can't think of a programming discussion that lends itself to that kind of explanation without a diagram or a piece of pseudocode somewhere in that discussion.

    Whereas code listings put me off for almost the same reason. Instead of a huge listing, give me a diagram or explanation of the overall concept. Show me code when there's interesting syntax, techniques, or unfamiliar approaches being used.

    Some examples taken from the resources on the shelf over my head right now:

    • Good: K&R. Nowhere do they talk for more than half a page without showing a small code example of what they're trying to say. Yet there's no long listings in the book anywhere.
    • Bad: merlyn's Web Techniques columns. He's usually got one interesting tidbit and surrounds that with a page of stuff that really isn't showing off anything new. Worse, the explanation of the interesting bit is buried in the pages of comments disguised as text.
    • Good: Programming Perl 3ed. The long discussions in there are usually about the language author's intent and not about the programming itself. Otherwise a nice balance between code and description.
    • Bad: Perl Web Site Workshop. I helped to edit this, I don't like pages and pages of listings but it's what the authors/publisher wanted. A CD is included.
    • Good: Mastering Regular Expressions. Very, very good. Good use of diagrams and sparse use of code except when needed.
    • Mixed: Stevens, Unix Network Programming. For 4/5ths of the book very good. Little blocks of code to show off whatever he's talking about. When he gets into his tftp and lpr servers... it gets a little ridiculous.
    Now this is just about the code/text balance. I'm not commenting on the actual quality of the books in question. :)