Debuggable explanations

I’ve been reviewing Greg Wilson’s current book project, Software Design in Python. Like the earlier JavaScript-based Software Design by Example it’s a guided tour of tools, techniques, and components common to many software systems: testing frameworks, parsers, virtual machines, debuggers. Each chapter of each of these books shows how to build the simplest possible working version of one of these things.

Though I’ve used this stuff for most of my life, I’ve never studied it formally. How does an interpreter work? The chapter on interpreters explains the basic mechanism using a mixture of prose and code. When I read the chapter I can sort of understand what’s happening, but I’m not great at mental simulation of running code. I need to run the code in a debugger, set breakpoints, step through execution, and watch variables change. Then it sinks in.

The GitHub repo for the book includes all the text and all the code. I’d like to put them side-by-side, so that as I read the narrative I can run and debug the code that’s being described. Here’s how I’m doing that in VSCode.

This is pretty good! But it wasn’t dead simple to get there. In a clone of the repo, the steps included:

  • Find the HTML file for chapter 3.
  • Install a VSCode extension to preview HTML.
  • Find the code for chapter 3.
  • Adjust the code to not require command-line arguments.
  • Arrange the text and code in side-by-side panes.

Though it’s all doable, the activation threshold is high enough to thwart my best intention of repeating the steps for every chapter.

Whether in VSCode or another IDE or some other kind of app, what would be the best way to lower that activation threshold?

Posted in .

8 thoughts on “Debuggable explanations

  1. So many years I’ve been following your work! But this as just a “hello!”

    I’ve worked with a good number of very good fellows. And at U, with some folk (male and female both) who evidenced clearly how I am //not// brilliant and they definitely were!

    In a very difficult MilSpec avionics R&D project, doing tech_docs and change management, I was daily in touch with global masters in various domains. But one stood out … and I think it shines a light on a small aspect of this:

    He wrote amazing code for the complex, real time data processing required by BITE (Built In Test Equipment) demanded by aviation landing systems. Management had to let him go. For why? we couldn’t maintain his code. Almost nobody could grasp his algorithms!

    With Z80 and 6502 I didn’t just learn Assembler. I wrote in true machine language. Move this byte here. Toggle that bit there. Wonderful. Seeing right back into Joseph Jacquard’s thinking! (1801 … more than 2 centuries ago)

    cheers to you, good fellow

  2. This is a tall order, Jon! And a solution for one book isn’t going to work for another. Untangling the code from the HTML surrounding each piece would be pretty hard. Instead, I would be inclined to modify the CSS style sheet so that only the code displays, then select and copy the parts of the code you want to play with into another document or node or extension (according to the software you use). I would start with something like

    * {display: none;}
    code * {display: contents;}

    If you know enough about writing extensions, you could add a hotkey that copies the selected text into an open document in VSC. A little more advanced, it would probably be possible to use another hotkey to toggle the stylesheet into/out of the code-only mode.

    Getting that going would take a certain amount of work, but once it was working, it would work for all parts of the book. And it would probably work for a number of other books with small changes (e.g., different CSS elements).

    You would still have to find the right HTML chapter (or the whole document), but you have to do that somehow anyway.

  3. Now that is very nice! I see that the book creation system, mdbook, sends the code to a rust site called the “playground”. IOW, to some kind of a language server.

  4. > Whether in VSCode or another IDE or some other kind of app, what would be the best way to lower that activation threshold?

    I’m very excited about online IDEs like GitPod and GitHub Codespaces for this.

    Click a link, get a fresh development environment running in your browser with a text editor and all of the dependencies you need already installed.

  5. is this not what an interactive notebook could do? maybe something else is missing?

    1. Yes, Greg and I thought Jupyter could work for this, but the dataflow model isn’t well suited for this, and also no debugger.

Leave a Reply