Comments are good, this particular instance, not so much.

This description spends a lot of time stating the blindingly obvious, eg:

    if (addedFiles.length === 0) {
      // Abort if no files matched path.
      throw new Error(files.pathFromRepoRoot(path) + " did not match any files");

Or:

    // If --bare was passed, write to the Git config indicating that the repository is bare.
    // If --bare was not passed, write to the Git config saying the repository is not bare.
    config: config.objToStr({ core: { "": { bare: opts.bare === true }}}),

This really adds no information if the names are clear and you can read JS. The important thing isn't what is happening in the code, because you already can see that in the code. It's WHY. For instance, it'd be far more useful to explain what is a 'bare repository', what are the implications of it, and why are we keeping track of that data, than to say "If it's bare, we write in the file that it's bare".

I feel that explaining TLS and similar in this manner would be completely unhelpful. Check out this document, for instance, specifically the "Algorithm for crypt" part:

https://www.akkadia.org/drepper/SHA-crypt.txt

Very well explained. But try and tell me what's the purpose and why those specific steps, which look increasingly bizarre as you delve in, and whether deviating from any given step would be acceptable or not (ignoring matters of compatibility)

You don’t have to explain TLS in this manner, but you could comment the relevant specification paragraphs next to the code to facilitate audits.

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.

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

What is the tool that builds this literate source view from source code?

My guess is it's Docco: http://ashkenas.com/docco/

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

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

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.

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

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

> 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.

It's a very old idea. Donald Knuth implemented it with both Pascal and C to promote an idea of "literate programming" -- you'd literally just write prose sprinkled with little bits of programming. On compilation, you can choose to compile either the documentation or program.

The deep learning library fastai uses this. Their source code is also their documentation. They use something called "nbdev" to accomplish this. And I have also seen other projects both related and unrelated to deep learning adopt it. This idea stems from Knuth.

For an example, the PBRT book is great.

PBRT is Physically Based Rendering: From Theory To Implementation by Matt Pharr, Wenzel Jakob, Greg Humphreys.

https://www.pbrt.org

https://www.pbr-book.org

https://www.amazon.com/Physically-Based-Rendering-Theory-Imp...

> This book has deservedly won an Academy Award. I believe it should also be nominated for a Pulitzer Prize — Donald Knuth

It's hard to beat that book review.

Here is some JWT minting and parsing you can run in the browser https://observablehq.com/@tomlarkworthy/firebase-admin ported from MIT licensed firebase-admin Github repo.

Oauth 2.0 clients https://observablehq.com/@tomlarkworthy/oauth-examples

This is a WIP but its a full on Identity Provider implemented the browser it a literate programming env! https://observablehq.com/@endpointservices/auth