News for hackers. Stuff that matters.
Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by pmiller2 on Tuesday April 13, 2021 @01:03AM (#26788274)
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/ for more information and examples.

Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by jacobolus on Tuesday April 13, 2021 @01:11AM (#26788318)
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://coffeescript.org/annotated-source/lexer.html

https://backbonejs.org/docs/backbone.html

Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by bollu on Tuesday April 13, 2021 @01:51AM (#26788522)
What is the tool that builds this literate source view from source code?
Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by pmiller2 on Tuesday April 13, 2021 @02:47AM (#26788878)
My guess is it's Docco: http://ashkenas.com/docco/
Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by Varriount on Tuesday April 13, 2021 @05:26AM (#26789986)
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

Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by krageon on Tuesday April 13, 2021 @06:18AM (#26790324)
Yes, they have to start somewhere. That somewhere is reading and working with the code they want to read slowly.
Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by kevin_thibedeau on Tuesday April 13, 2021 @01:43AM (#26788489)
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.
Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by colejohnson66 on Tuesday April 13, 2021 @09:15AM (#26791717)
Or the OG TeX for that matter. Knuth writes his code in WEB (his own literate programming language based on Pascal)
Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by baby on Tuesday April 13, 2021 @02:00AM (#26788567)
I think that this is something else, it's a simple difference but having the code on the size changes everything for me.
Re:Gitlet.js – Git implemented in 1k lines of JavaScript (2015) by platinumrad on Tuesday April 13, 2021 @02:48AM (#26788889)
> 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.