From: Peter Seibel
Subject: Seeking comments on code explanations
Date: 
Message-ID: <m3vfcvke6d.fsf@javamonkey.com>
For anyone who happens to be thinking of sending me comments on my
book[1], particularly, on the practical chapters, I'd be particularly
interested in your thoughts on how the explanations of the code are
working. I find myself constantly struggling trying to find the right
balance between explaining too much of the code in prose vs just
dropping in big piles of code and expecting it to speak for itself .
Also do you prefer to get a chunk of code followed by a prose
explanation or a prose explanation of roughly how some code works
followed by the actual code?

-Peter

[1] <http://www.gigamonkeys.com/book/>


-- 
Peter Seibel                                      ·····@javamonkey.com

         Lisp is the red pill. -- John Fraser, comp.lang.lisp

From: Steven E. Harris
Subject: Re: Seeking comments on code explanations
Date: 
Message-ID: <jk4hdof24a5.fsf@W003275.na.alarismed.com>
Peter Seibel <·····@javamonkey.com> writes:

> Also do you prefer to get a chunk of code followed by a prose
> explanation or a prose explanation of roughly how some code works
> followed by the actual code?

I prefer a combination: A prose introduction of intent, the chunk of
code, then clarifying prose focusing on new or unusual constructs
used. That way I know something about the code I'm about to read, and
I'm enticed to continue reading after studying the code for help
understanding the parts that may have gone over my head.

-- 
Steven E. Harris
From: Tayssir John Gabbour
Subject: Re: Seeking comments on code explanations
Date: 
Message-ID: <1098950094.572569.231870@z14g2000cwz.googlegroups.com>
Steven E. Harris wrote:
> Peter Seibel <·····@javamonkey.com> writes:
>
> > Also do you prefer to get a chunk of code followed by a prose
> > explanation or a prose explanation of roughly how some code works
> > followed by the actual code?
>
> I prefer a combination: A prose introduction of intent, the chunk of
> code, then clarifying prose focusing on new or unusual constructs
> used. That way I know something about the code I'm about to read, and
> I'm enticed to continue reading after studying the code for help
> understanding the parts that may have gone over my head.

I agree. I suspect I'm happiest when authors gets to the "heart" or
"philosophy" of something in deft words, then proceeds along the lines
you have in mind. When it's appropriate, of course.

MfG,
Tayssir
From: mikel
Subject: Re: Seeking comments on code explanations
Date: 
Message-ID: <fs1gd.12412$6q2.11071@newssvr14.news.prodigy.com>
Steven E. Harris wrote:

> Peter Seibel <·····@javamonkey.com> writes:
> 
> 
>>Also do you prefer to get a chunk of code followed by a prose
>>explanation or a prose explanation of roughly how some code works
>>followed by the actual code?
> 
> 
> I prefer a combination: A prose introduction of intent, the chunk of
> code, then clarifying prose focusing on new or unusual constructs
> used. That way I know something about the code I'm about to read, and
> I'm enticed to continue reading after studying the code for help
> understanding the parts that may have gone over my head.

I agree.

In addition, sometimes I've found it useful, if the code is particularly 
involved or uses very unfamiliar or difficult concepts, to present the 
chunk of code and then call out the particularly juicy bits separately 
in single lines to explain them in detail.