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
comments
gav on 2002-03-16T00:47:23
Personally I like variable width fonts and I don't ever run code anyway.
hmm... I probably should have been more helpful
:)
gav
please no long blocks of code
ask on 2002-03-16T00:54:56
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 of code that way, but I just recall because it had a good flow.
Did I mention that I think long codeblocks, page by page, really sucks?
- ask
Re:please no long blocks of code
pudge on 2002-03-16T13:30:59
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.
what about both?
geoff on 2002-03-16T01:49:30
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...
Presentation
quidity on 2002-03-16T02:02:49
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.
like Programming Python
kellan on 2002-03-16T03:27:58
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.
just do the entire book
hfb on 2002-03-16T05:02:36
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.
In smallish chunks but...
pdcawley on 2002-03-16T07:18:29
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 one of those 'If I were you, I wouldn't start from here' answers?
Another example
djberg96 on 2002-03-16T12:41:33
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
clintp on 2002-03-16T21:05:32
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.
:)
Petzold -- Look at his books
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 personally find that I learn the material better by typing it and working through it.
(One of the problems that I had with the Perl cookbook (sorry) was that at times, new things just appeared in one of the recipies, and I would go running through the book to try and find how this or that worked. )
Make each program different
Odud on 2002-03-18T09:32:52
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.
Re:Make each program different
ask on 2002-03-18T14:12:46
who would ever type in the program anyway? Put the complete code on a website and just show it as snippets through the book.
