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
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
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
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.