small medium large xlarge

22 Nov 2010, 15:48
Travis Swicegood (117 posts)

Hey guys;

Just curious for some feedback on how you like to see code examples in a book. I tend to break up chunks of code into smaller bits, a line or two, and explain those lines. Add another chunk, explain it, and so on and so on. It works well for explaining each chunk. The problem is that you can’t see the entire code as a whole to get a feel for the larger chunk of code (let’s say 10 - 15 lines of code).

My question: do you prefer smaller chunks of code or one larger chunk that’s defined with a larger, uninterrupted block of text? As a third possibility, would you prefer the smaller set of code + the larger code block after the fact as a “here’s the whole block…” after each piece has been explained?

This is entirely a preference thing, so no right or wrong answer. Just curious for some opinions.


22 Nov 2010, 17:39
Larry Jones (89 posts)

It depends on the “mental size” of the code blocks.

Since I’m reading the code and not writing or debugging it, it needs to “fit in my brain.” Too long and I tend to scan it or skip it.

It is also difficult to find pieces of interest in source code in a book because my only “tool” is scanning the code for the pieces of interest.

I am sometimes willing to skip back and forth between the text and complete listings, but not always (I trust the author :) ).

Finally, I would be less willing to page back-and-forth using an ebook. If the detailed text was somehow linked to the full listing, I would move between the two; if they were not linked, I may print out the text to refer to the different pages.

22 Nov 2010, 18:10
UlrichMerkel (23 posts)

Hi Travis,

why not follow the maxime (as any news show):

Tell them what they will see: (just some inline comment what should be done and WHY)

Then go to the details: (implementing a small function after the other)

Then give them the complete picture again (assemble it all to get the complete thing working)

Success, Uli

22 Nov 2010, 19:05
Diego Zamboni (69 posts)

I think up to 10-15 lines I would prefer to see at once, with the explanation after it, since I can hold about that much code in my mind, and also easily refer back to it. For longer pieces of code, the best would be to split it into 10-15-line chunks that are explained in turn, and at the end be able to see the full thing to get an idea of how it all fits together.

22 Nov 2010, 19:39
Daniel de Kok (38 posts)

I like larger blocks (functions), nothing is more annoying than having to reassemble small snippets of code.

It also removes context.

23 Nov 2010, 04:22
Travis Swicegood (117 posts)

Thanks for the feedback, guys. My current model has been to break it apart into its contextual pieces (these two lines do this, check for that with this, etc.), then show the full code assembled at the end. I think it works, but then again most parents think their kids are the prettiest things ever. :-)


25 Nov 2010, 06:20
Josh Carter (40 posts)

+1 on Diego’s comment. I prefer to see the whole block as one, partly so I see each line of code in context, and partly because it’s easier when re-reading to scan for the block of code I remembered reading about earlier. I value dead-tree books greatly for the ease of flipping back through sections to jog my memory, and the eye is drawn to code samples – these are valuable landmarks in a programming text.

You must be logged in to comment