Giters

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

The very first build system for The Nature of Code

Home Page:http://natureofcode.com

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Introduce code display syntax

scotthmurray opened this issue · comments

commented

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.

commented

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.