code convention discussion

[shiffman]

Picking up on comments from @alignedleft in this thread: nature-of-code/The-Nature-of-Code-archive#350 I now have the following in edition 2:

Any feedback @alignedleft?

[scotthmurray]

That is helpful! FWIW:

• Why is the sidebar on "code formatting" inserted after the first code snippet? This further interrupts the code being explained.
• Do you use the same gray shading for sidebars as for connecting passages of code and their comments? Since both appear back to back here and they are the same width, they feel related.
• What does the "(like)" comment mean?

Alternately, you could have an example with dummy code earlier in the chapter/book, just to illustrate the styles used and introduce how you will be interleaving code and text.

[scotthmurray]

That's great! Much more clear, at least for me.

I'd suggest instead of "light grey highlighting matches the comments…" consider "light grey highlighting groups the comments…"

One more design idea (may not be feasible): Since there may be many of these interrupted snippets throughout the book, what about signifying the start of a code example with, say, a solid black border on the top edge of the snippet (preceding class Walker {, in this case). The end of a snippet could be indicated with the same border on the bottom edge of the final excerpt.

For that matter, I'd suggest using a different color or gray for code/comment highlighting than the gray used for sidebars and other callouts.

[shiffman]

Here I am again three years later! @scotthmurray not that I expect you to follow this but you can see the latest here:

https://nature-of-code-2nd-edition.netlify.app/introduction/#i2-the-random-walker-class

@jasongao97 what do you think about the suggestion of having a horizontal gray line / bar for when a code snippet begins and closing it with another when the snippet ends (see blue lines below). My gut feeling is this is going to be complex to maintain and apply consistently (since a lot of code snippets are stand alone, but I am open to considering it.)

[scotthmurray]

Well, color me impressed! 😁

[jasongao97]

@shiffman Technically speaking, I believe it's not hard to implement. We can just set a new callout block type and drag everything inside. e.g. the following. But I'm wondering if there are any other design choice besides a start/finish line.

• Maybe adding a vertical line with indent for the whole section.
• Or add ... notations at the top or bottom of code blocks to infer a continuous block above/below.

[shiffman]

Yeah, I don't have a clear idea here, maybe let's put a pin in this one and revisit later. It could be really helpful but doesn't feel as high priority as other things that need to be done for the book. I'm adding @nheidelberger to this thread in case he has any thoughts!

[shiffman]

This discussion can be followed in #447!