Site to Read Real Code (Like Python)
January 26, 2018 6:44 PM   Subscribe

Website that would show programming code alongside English explainaction on what the code does?

I would love a website or somewhere online that would show an entire series of programs or code in a given language and then on along the side in English explain generally, more or less, what the code does. I feel that that would greatly help me understand how code works.

Is there any such site?
posted by alice_curiouse to Technology (6 answers total) 20 users marked this as a favorite
Questions of the month at
posted by Lanark at 2:35 AM on January 27, 2018

Best answer: 500 Lines or Less, which you can buy as a printed book or read online for free?
posted by James Scott-Brown at 2:54 AM on January 27, 2018 [1 favorite]

I feel that that would greatly help me understand how code works.

Programmer here, since the punch-card era, and my feeling is, the best way to understand how code works is by writing, compiling and testing code. Part of that process is adding explanatory comments which are embedded into the code itself -- I've never heard of placing these alongside. Some developers resist this practice. All-comment pseudo-code is written sometimes, which is then converted to code. Analyzing programs with lots of comments could help you, but textbooks and CS courses generally use a more granular, incremental approach.
posted by Rash at 8:55 AM on January 27, 2018

Best answer: Yes. This is called "literate programming". A program with a prose description alongside (or, more usually, interleaved in vertical blocks) is called a "literate program". There are many
examples on the web, but also in books, papers and technical reports. Literate programming was named, and more or less invented, by the deservedly famous Donald Knuth, who wrote a book length literate program about his TeX typesetting program, as well as many shorter examples.

Here is an example of a literate program in side-by-side format. It is a Javascript program that implements the basics of the git version control system:

Here is another side-by-side example. It is a Python program that implements a very simple interpreter for the Lisp programming language.
posted by JonJacky at 9:21 PM on January 27, 2018 [1 favorite]

Best answer: PS. In Python, many programs presented in IPython notebooks (with the .ipynb extension) or Jupyter notebooks are literate programs. Here is a treasure trove of such by the esteemed Peter Norvig. I think this is exactly what you are looking for:
posted by JonJacky at 9:46 PM on January 27, 2018 [1 favorite]

Safia Abdalla has written a whole bunch of code reads and dives into other technical papers etc. on her blog. So far she's covered Node.js and various modules; git, curl, scrypt, and Redux (and has written a lot of other cool tech-concentric stuff too!).
posted by postmillenial at 12:14 AM on April 23, 2018

« Older GPS stands for Gross Panicky Stress   |   How to *thrive* without a family? Newer »
This thread is closed to new comments.