Hi all; I'd like to use Literate programming in Visual Studio Code for js. Anyone doing that? E.g Plug-in recommendations would be appreciated. Ideally I'm looking for something with a subset of similar features to what [@ibdknox] Chris Granger did for Eve []; Free source code ordering, ability to add some interactivity using the code itself etc, mix markdown and js. That should be pretty doable, don't you think? Thing is I've got a perfect use-case for literate programming in a current project; not much code, just a few hundred LOC, but conceptually heavy. So I'm not in need of any deep magic, it's enough if Literate Programming would: (1) help me understand my own underlying model. (2) Produce something useful to others wanting to understand the code/underlying model later (without extra work on my side 🙂 ). That would be great! Recommendations/ideas/experiences are super welcome!

Observablehq.com is literate programming but not in VSCode. Its online in the browser, which for me is better (Chrome dev tools). There is an attempt at porting to vscode: https://marketplace.visualstudio.com/items?itemName=GordonSmith.observable-js but I do not know how well that works.

Wow, thanks @Tom Larkworthy! That sounds great! I'll check it out; What are your experiences with LP; For what projects do you find it useful etc?

everything

Probably not relevant to you, but I use an unconventional form of literate programming that includes tests and an explicit history of the project: http://akkartik.name/post/wart-layers. I think LP is awesome, and there's wide open spaces for making it even more awesome.

All my comments are war stories.

Reminds me of Notes on the Synthesis of Form, with its focus on "misfits." For every design choice, say what you don't want to happen.

In literate programming, test cases can become part of documentation. "When you do X, Y will happen, e.g. <ACTUAL EXECUTED CODE WITH ASSERTION AND THE ABILITY FOR THE READER TO EDIT>" I have a reactive unit testing library for Observablehq (@tomlarkworthy/testing). Observable has in built version history so you don;t get to add "commit description", but for things like major releases I write a change log entry in prose as part of the notebook text.

Hey, Kartik Agaram, Your approach using layers both was really helpful to me! It made me realize that it would be simpler if I solve a small clean subset of the whole thing in a first version, and then add one thing at a time. Since I’m learning/discovering how things should be work while writing the code, it is really helpful to be able to go back and look at a simpler version, complete with examples and explanations, and then just focus on understanding the diff 🙂 . As an aside, I couldn’t really call it

layers

since that is the name of the fundamental abstraction i my project 🙂; I tried with

levels

but it was too similar; couldn’t keep them clearly apart in my mind, so for now I just use

chapters

; that reminds me that I can look at it like a writing project, and keep nibbling on it in the spirit of “Write now” by Harold Thimbleby.