4 ms·

As @chungy says in a sibling comment, this is what's known as a literate program. It never really took off, and I suspect it's partially because doing it well

As @chungy says in a sibling comment, this is what's known as a literate program. It never really took off, and I suspect it's partially because doing it well means you'll be writing a lot more text than you'd typically see in a program's comments. See http://www.literateprogramming.com/ http://www.literateprogramming.com/ for more information and examples.

jacobolus 6y ago
The particular method of turning javascript comments into a "literate" source view, used in the link under discussion here, comes from Jeremy Ashkenas circa 2009, e.g.: https://underscorejs.org/docs/underscore-esm.html https://underscorejs.org/docs/underscore-esm.html https://coffeescript.org/annotated-source/lexer.html https://coffeescript.org/annotated-source/lexer.html https://backbonejs.org/docs/backbone.html https://backbonejs.org/docs/backbone.html
- bollu 6y ago
  What is the tool that builds this literate source view from source code?
  - pmiller2 6y ago
    My guess is it's Docco: http://ashkenas.com/docco/ http://ashkenas.com/docco/
kevin_thibedeau 6y ago
Try and read the source to Metafont. It's a scattered morass with blocks of code broken out from it's point of usage for expository purposes.
- colejohnson66 6y ago
  Or the OG TeX for that matter. Knuth writes his code in WEB (his own literate programming language based on Pascal)
baby 6y ago
I think that this is something else, it's a simple difference but having the code on the size changes everything for me.
- platinumrad 6y ago
  > I think that this is something else, it's a simple difference but having the code on the size changes everything for me. I assume you mean "on the side" and I agree, it's a game-changer. Normally I find literate programs to be tedious to read but simply changing the layout makes a huge difference.
Varriount 6y ago
Huh. I actually write my code in this style. Perhaps not quite as detailed, but with the same idea in mind. I wish code like this was more common. Over and over, I've heard fellow programmers reply with something along the lines of "well it should be obvious what it does! just look at the name and implementation - all you need is right there", when it was suggested that they add documentation to their implementations. What never seems to quite get across fully is that, yes, the code is all there, and it may even be clean and fairly readable, but the inherent complexity is such that only programmers experienced in subject X will ever have a chance of actually understanding it. "So, what? If it's that complex, then maybe only programmers who are that experienced should attempt to read and/or contribute to it"* is another sentiment I've seen expressed. Of course, this misses the logic that, in order for such programmers to exist, they have to learn from somewhere, and start from something. And how will we ever have programmers experienced in that subject
- krageon 6y ago
  Yes, they have to start somewhere. That somewhere is reading and working with the code they want to read slowly.

jacobolus 6y ago

The particular method of turning javascript comments into a "literate" source view, used in the link under discussion here, comes from Jeremy Ashkenas circa 2009, e.g.: https://underscorejs.org/docs/underscore-esm.html https://underscorejs.org/docs/underscore-esm.html https://coffeescript.org/annotated-source/lexer.html https://coffeescript.org/annotated-source/lexer.html https://backbonejs.org/docs/backbone.html https://backbonejs.org/docs/backbone.html

bollu 6y ago
What is the tool that builds this literate source view from source code?
- pmiller2 6y ago
  My guess is it's Docco: http://ashkenas.com/docco/ http://ashkenas.com/docco/

kevin_thibedeau 6y ago

Try and read the source to Metafont. It's a scattered morass with blocks of code broken out from it's point of usage for expository purposes.

colejohnson66 6y ago
Or the OG TeX for that matter. Knuth writes his code in WEB (his own literate programming language based on Pascal)

baby 6y ago

I think that this is something else, it's a simple difference but having the code on the size changes everything for me.

platinumrad 6y ago
> I think that this is something else, it's a simple difference but having the code on the size changes everything for me. I assume you mean "on the side" and I agree, it's a game-changer. Normally I find literate programs to be tedious to read but simply changing the layout makes a huge difference.

Varriount 6y ago

Huh. I actually write my code in this style. Perhaps not quite as detailed, but with the same idea in mind. I wish code like this was more common. Over and over, I've heard fellow programmers reply with something along the lines of "well it should be obvious what it does! just look at the name and implementation - all you need is right there", when it was suggested that they add documentation to their implementations. What never seems to quite get across fully is that, yes, the code is all there, and it may even be clean and fairly readable, but the inherent complexity is such that only programmers experienced in subject X will ever have a chance of actually understanding it. "So, what? If it's that complex, then maybe only programmers who are that experienced should attempt to read and/or contribute to it"* is another sentiment I've seen expressed. Of course, this misses the logic that, in order for such programmers to exist, they have to learn from somewhere, and start from something. And how will we ever have programmers experienced in that subject

krageon 6y ago
Yes, they have to start somewhere. That somewhere is reading and working with the code they want to read slowly.