11 ms·

So, I'm going to put that out there, but I really wish I could read security-sensitive code like this. TLS implementations, cryptographic implementations, etc.

by baby 6y ago

So, I'm going to put that out there, but I really wish I could read security-sensitive code like this. TLS implementations, cryptographic implementations, etc. It would be really amazing if there was a way for Github to automatically display code like this by extracting comments out. In general I think it's an amazing way of learning, I remember reading the gobyexample.com website and writing the same thing for go assembly: https://davidwong.fr/goasm/add https://davidwong.fr/goasm/add

chungy 6y ago
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.
- someoldguy 6y ago
  For an example, the PBRT book is great.
  - WalterGR 6y ago
    PBRT is Physically Based Rendering: From Theory To Implementation by Matt Pharr, Wenzel Jakob, Greg Humphreys. https://www.pbrt.org https://www.pbrt.org https://www.pbr-book.org https://www.pbr-book.org https://www.amazon.com/Physically-Based-Rendering-Theory-Implementation/dp/0128006455 https://www.amazon.com/Physically-Based-Rendering-Theory-Imp...
    - jonas21 6y ago
      > 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.
- truthr 6y ago
  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.
pmiller2 6y ago
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)
- 6y ago
tlarkworthy 6y ago
Here is some JWT minting and parsing you can run in the browser https://observablehq.com/@tomlarkworthy/firebase-admin https://observablehq.com/@tomlarkworthy/firebase-admin ported from MIT licensed firebase-admin Github repo. Oauth 2.0 clients https://observablehq.com/@tomlarkworthy/oauth-examples 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 https://observablehq.com/@endpointservices/auth
dale_glass 6y ago
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 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)
- baby 6y ago
  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.

by baby 6y ago

chungy 6y ago

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.

someoldguy 6y ago
For an example, the PBRT book is great.
- WalterGR 6y ago
  PBRT is Physically Based Rendering: From Theory To Implementation by Matt Pharr, Wenzel Jakob, Greg Humphreys. https://www.pbrt.org https://www.pbrt.org https://www.pbr-book.org https://www.pbr-book.org https://www.amazon.com/Physically-Based-Rendering-Theory-Implementation/dp/0128006455 https://www.amazon.com/Physically-Based-Rendering-Theory-Imp...
  - jonas21 6y ago
    > 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.
truthr 6y ago
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.

pmiller2 6y ago

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)
6y ago

tlarkworthy 6y ago

Here is some JWT minting and parsing you can run in the browser https://observablehq.com/@tomlarkworthy/firebase-admin https://observablehq.com/@tomlarkworthy/firebase-admin ported from MIT licensed firebase-admin Github repo. Oauth 2.0 clients https://observablehq.com/@tomlarkworthy/oauth-examples 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 https://observablehq.com/@endpointservices/auth

dale_glass 6y ago

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

baby 6y ago
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.