nature-of-code / The-Nature-of-Code-archive

The very first build system for The Nature of Code
http://natureofcode.com
913 stars 151 forks source link

Introduce code display syntax #350

Closed scotthmurray closed 8 years ago

scotthmurray commented 10 years ago

In the introduction ( http://natureofcode.com/book/introduction/ ), when I read the first code sample, introducing the Walker class, I was confused for three reasons:

1) The code snippet is not self-contained, but rather continues below, interrupted by commentary. This is not a problem itself, but for some reason, I was expecting a closing bracket, and thought it was missing.

2) The first line of this snippet is not shaded gray, but the latter 2 lines are. It was unclear to me at first why that was the case. (Once I read ahead to a few more examples, it made sense. But it was confusing initially.)

3) In my copy (print version 1.0), the first line of this snippet is on page 2, and the rest is on page 3.

Since this is the first code sample in the book, could you add a comment introducing the visual syntax? (E.g., code is written in this font, and commented areas are shaded gray…) I love how clearly you introduce the Examples on the following page, beneath the reference to Example I.1. Perhaps you'd consider using a similarly clear introductory note here.

shiffman commented 10 years ago

Thanks Scott, this is really helpful, agree with your assessment. I'll take a closer look when I do a next round of updates on the book.

shiffman commented 8 years ago

Now tracked in new repo: https://github.com/shiffman/The-Nature-of-Code/issues/98