Stories
Slash Boxes
Comments
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

use Perl Log In

Log In

[ Create a new account ]

gnat (29)

gnat
  (email not shown publicly)

Journal of gnat (29)

Friday March 15, 2002
07:26 PM

Handling code in books

[ #3579 ]
What to do when there's a big long program that you want to talk about?

Present it chunk by chunk? Makes it a pain in the ass to type in, or copy'n'paste from Safari (which, being in a country far far away from my ORA book collection, I have grown to love).

Present the whole program and then talk about it? Do you reproduce the fragments you're talking about? Number lines? (Line numbering loses you valuable columns for code, and anyone who has ever line-broken code for publication knows what a precious resource they are). Bold lines of code in the initial presentation?

So many decisions! Can you remember a book with large code examples where the discussion of the code examples was easy to follow? Tell me how they did it! If you can only remember books where it didn't work, still tell me!

Thanks,

--Nat

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Personally I like variable width fonts and I don't ever run code anyway.

    hmm... I probably should have been more helpful :)

    gav

  • long blocks of code sucks. Even if it's to show something cool. I always just skip over long pages of code and just read the discussion of it; referring back to the code if I have to. I don't always get a lot of out of that, go figure.

    If it's to demostrate a concept; then show the concept with text and diagrams. If it's to show cool code; well, maybe it isn't so cool if it takes several pages to explain.

    In other words: I prefer the "in smaller chunk" approach. Maybe I have happily read long snippets o
    --

    -- ask bjoern hansen [askbjoernhansen.com], !try; do();

    • I have to agree with this. If you are going to put large blocks of code (> 1 page) in a book, put them in an appendix and refer to it, and put in only the smaller blocks you're referring to in the chapter itself. Always use monospace fonts (as long as Il1|, 0O, etc. can be differentiated, I am happy) and number ever line.
  • I think the way the eagle book does it sometimes works: chuncks of code, follwed by explanations, then the entire program at the end. before writing a book I thought it was just filler to puff the page count, but I can see the value in it now, appealing to both types of readers. for ours I chose to put all the code together and include longish comments that were different from the discussion following the code - I'm still not sure if it was the right approach, though...
  • For presentations I tend to rewrite the code to just have the bits I care about (removing half the error checking, renaming variables to be shorter, putting in elipsis here and there), then make sure the whole example fits on one screen. Then I decide which bits I want to talk about, and provide a series of slides with the important bits highlighted in red as I talk about them. If I'm going to be entirely sequential then I'll start with all the code grey, and turn it black as I talk about it.

  • I like the way Programming Python 2nd ed handles it. You get the full listing, and then the relevant bits as they get discussed. Best of both worlds. Unfortunately is 1200 pages long.
  • In courier :)

    Brevity is what I look for in code samples...shit that goes on for pages means I'm going to have to flip pages and right there, I'm not interested. I liked the perl cookbook with little chunks and small lessons building up to a full program at the end.

    Concise, Illustrative, Correct code.

  • Refactor the program. Mercilessly. Use the 'Composed Method' pattern a lot. All the arguments about intention revealing code apply in spades when you're looking at a book which you can't grep easily grep through.

    When each method is short and does one thing, or does more than one thing by delegating to other well named methods, it's relatively easy to discuss a method in isolation. Also, short methods tend not to involve deep indentation, which is a big win in a book.

    Why do I get the feeling that this is o
  • Others here have made good suggestions. I personally like Lincoln Stein's method for Network Programming with Perl. Whole modules/programs presented (usually 1 page or less), and then explained by blocks of line numbers and/or subroutine.
  • Long code block (Score:2, Informative)

    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

  • The two of his that I have have a couple of things that make the multipages of code, that he lists easier to digest and comprehend.

    1. First lots of white space

    2. The code is well factored.

    a. It is broken down into subcomponents

    b. It builds of previously explained code.

    c. He shows you six different ways to do the same thing(like create a window), but when you are done, you know all of the ways to do it.

    True his books are 1,000+ pages, and are designed so that you type all of the code in, but I per

  • I once read a book (on c) where the author presented a large number of programs - each program built on the previous one - and we ended up with a full(ish) application. Seemed a good idea but because the programs were so similar it was difficult to get a feel for where you where in the book. It would have been better to make each one look different from it's neighbours. Also as someone else suggested putting the complete code in as appendices and just quoting fragments in the body may work better.