What's the best way to clearly show differences between two blocks of code?

[carols10cents]

From #180 (comment).

Problem

If we start with one pretty sizeable chunk of code, and then modify it to build on it, we need to make it clear what parts have been added, modified, or deleted when going from the first block to the second block. This will help readers to follow along with less of a chance of getting a weird error because they missed an edit.

Possible solutions

• Suggested by nostarch: bold the code that has changed
  • Problem: additions and edits look the same, deletions are hard to see
  • Suggested solution to the deletion problem by @phrohdoh - use strike-through for deletion
  • Does bold and strike-through make the code look too different from how code is expected to look? Would intra-line edits lookwork ok?
• Hide the lines that haven't changed
  • Hard to see where the changes are in context, again hard to see deletions
• Use git diff syntax, with line numbers ideally
  • Is this readable and familiar enough to be understandable?

[carols10cents]

I just flipped through Land of Lisp to see if/how they handled this (since it's also a nostarch book, albeit about 5 yrs old). They have a general code annotation system with little circled numbers:

It's sometimes but not always used to point out changes.. in this example, there's a line removed between the 1st and 2nd code blocks and it's not annotated in any way, just pointed out in prose.

The Ruby Programming Language has a couple of spots that are side-by-side that i kind of like (diff -y is also my favorite diff format):

but this might not always work if the lines are long :-/

[azerupi]

How do other books handle this?

I'm not sure how your french is, but the long-form tutorials on OpenClassrooms are in the most well-written ressources for french speaking people who are learning programming on their own. e.g. their C++ tutorial. Maybe you can draw some inspiration from there?

For this particular issue, they seem to repeat most of the code. Eventually indicating missing snippets with //… when some part is less relevant. This is a good way to give context and repeat / drill in the important parts.

[carols10cents]

I've talked about this with our editor at nostarch and we're going to do a combination of cutting down the context (but still giving some context), bolding, and the circled numbers like in land of lisp. I think that'll cover it, for print at least.

So I'm changing this to be labeled "after print" -- I think it's also a valid issue online, but we have things like toggling open/closed, offering multiple formats, linking to diffs, etc that we have at our disposal on the web.

[carols10cents]

I'm in an issue-cleaning-out mood, and since we have resolved this for print, I'm closing this unless people have an issue with how the online book presents this.