Hacker News Reader

> should be taken more as an endorsement of his skill than the tools

Or that Knuth, as smart as he is, has not been able to transmit and explain to you how to do what he is actually doing (only what he thinks he is doing by, for example, outside/indirect observation).

Or maybe the literate approach is better for thinking in english (and perhaps mathematics) and then verifying it in each (tiny) software module.

I've spent a lot of time thinking about what skills are actually needed here, maybe not as much time as Knuth has, but I have the benefit of learning from his work: I don't use a literate style (indeed, I prefer the much more compact style[1]) and I don't have a strong mathematics background.

What I do is try to make my programs as small as possible so that it's simply not possible for any bugs to hide in them. Yes that means whitespace, not binary size. Then I compose my application out of a few small programs.

I sat on the plane recently next to a guy proofreading a manuscript. He had five phones out next to his laptop, all with various parts of his document open on them, scrolling on each. I didn't want to disturb him to ask him what he was thinking, but was nonetheless fascinated by his process.

I intend to try experimenting with a lot of little displays for my programs next.

[1]: https://github.com/geocar/dash/blob/master/d.c#L61

> One of my favourite examples of this is APL, where those experienced can read and write programs in it as easily as they can a human language; programs which are completely incomprehensible to anyone who doesn't know the language.

APL has got anywhere from 30-70 or so builtins (depending on how you count and the specific flavour of APL) and a very simple syntax. I think a lot of their "incomprehensibility" comes from how strange they look. If a literate approach can be useful for training a mathematician uncomfortable with programming Java and C# to use Java and C# effectively, then perhaps it can be used for teaching APL.

Assuming you have a dictionary of your alphabet:

    A←'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPRQSTUVWXYZ0123456789'

and a way to collect the contiguous "words" from some input:

    words←{1↓¨(~x∊A)⊂x←' ',⍵}input

which is easy to understand if you break it up; the key part is `x∊A` which generates a bitmap of the locations where our input is a member(∊) of our alphabet. We negate(~) it since we want the breaks, and then we then take that bitmap and pick(⊃) out the breaks. Note I put something not in the alphabet at the beginning of the input so that `x` will begin with a break.

Next we'll want the unique words without an empty word (likely if we have multiple breaks in a row):

    unique←(∪words)~⊂''

and to know how many there are:

    counts←+/unique∘.≡words

By doing a match on each word against the unique word `∘.≡` we build a 2d bitmap which is as wide as length of the unique words, and as tall as the number of words - each cell denoting whether the word was the unique word we were comparing. You might try `unique∘.≡words` for yourself.

Lastly, we want the indices of the top (3) counts:

    i←3↑⍒counts

so that we can draw a nice table of the results:

    (⍪unique[i]),⍪counts[i]

You can try this at http://tryapl.com/

K/Q has a slightly simpler solution since it has a builtin "group" operator and more data types (like dictionaries), if you have something that makes words

    words:{"<"vs ssr[x;"[\000-@\133-`\173-~]";"<"]}

it's a simple matter to take some number (3) of the descending count of each group or:

    3#desc count each group words input

or in k:

    a!x a:3#>x:#:'=words input

which you can try by downloading the free version at https://kx.com

I find that literate programming is a little less relevant with programming languages that offer better abstractions and modularisation. With literate programming, you're free to structure your code in chunks, like:

  read numbers from file into array
  iterate over array
    add each element to sum
  display sum

Where you in Pascal/c would have to explicitly allocate temporary variables that doesn't really have anything to do with what you want to achieve.

Today we have languages with list-comprehension and iterators - and even c has good support for inlining functions - so you don't have to choose between abstract/clean and fast/clever.

C++17 even has some support for compile-time code execution, if I'm not mistaken.

Between all this, the structural improvements of a well-written literate program, are less important.

And finally - "archiving" or exposing features as programs or libraries - allow for a solid api and easy sharing and re-use of code/functionality across teams much more easily than copy-pasting chunks of code.

WEB-like systems do give languages like c, Pascal or java a macro-like extension with focus on ease of comprehension. But as we have better languages, that isn't very important anymore.

I do know of one example of an attempt to move a huge project to the literate style, the lisp symbolic system Axiom:

http://www.axiom-developer.org/axiom-website/currentstate.ht...

> Literate sources is the main thread of developing Axiom (...) > LITERATE SOURCES Motivation: Axiom needs to be well documented to live. To achieve this end it is being rewritten into literate software form.

I used literate programming to write ~25 programs last year, and I found that the coolest thing about the technique was crafting a narrative for understanding the problem and appreciating the solution.

One difficulty when reading somebody else's program is thinking "why didn't he just do X?" and not having a clear answer. In a good literate program—and it's harder to write good literate programs than simple programs—the author can touch on why a particular approach is unsuitable, or why he preferred one valid approach over another valid approach.

In the end, I think I prefer to write "regular code"; tools like editors, debuggers, build systems, etc. work better with real code. Still, I try to write doc-comments that inject better narratives in my programs and, hopefully, help the readers attain a better understanding.

I have tried several times to explain this idea. I almost think it should be called narrative programming.

I've found that getting to include the narrative is great when you're first writing it, and then for making small changes. But then, when something happens that changes your perspective on the problem, the structure of the narrative often needs to change substantially, while the structure of the code might not. And suddenly that formerly helpful narrative is a huge piece of legacy cruft that needs to be refactored... to support a few-line change in the actual code.

For that reason, I'm with you in that I try to write doc-comments that inject the narrative.

I'm curious if you have examples of times when the narrative changed dramatically.

I have found that it is easy to rat-hole thinking you know the entire structure and starting on the narrative of how you are writing it. I'm convinced most of even Knuth's programs were written a bit more holistically, and then a narrative emerged not necessarily of how the code was written, but how the code could be explained.

And really, this is no different than the other abstractions we have at our disposal. It is rare that the original function layout of the system survives for long. Why would you think your initial narrative would?

In theory, an IDE should be able to toggle between a literate programming layout and the actual structure that gets executed. Both views are valuable. If we take your argument to extremes, all programmers should write in assembly. Clearly programming supports very abstract levels of indirection, and in some cases a story is a natural way to organize code, such as when programming to a spec, implementing specific features, or developing a user experience. Interestingly, Git commit messages, branches, and tags have taken over some of these aspects of literate programming.

It should come as no surprise that you can do this with Emacs and org-mode.

Specifically, you can tangle a code block, jump to the code it created, edit it, and have that edit go back to the org file you tangled from. I believe I used that in this page, http://taeric.github.io/DancingLinks.html

I still hesitate to recommend literate programming for a team. But I have also grown to hesitate recommending/requiring large commit messages for the team. The reality seems that most folks do not write large messages, and fewer check the commits. It has literally been mind blurring to see folks that did not check the commits around a line of code to see why it was there.

I wholeheartedly agree. To me, Knuth's literate programs feel more incomprehensible than sanely structured programs with few strategically strewn in comments. Yet to be fair, one has to consider that the Pascal Knuth was working with offered significantly fewer structural elements than modern programming languages, so his meta-programming language WEB helps to mitigate this, as well as given some abstraction over a variety of Pascal implementations. But at the same time it is drowning the source code in prose, which, as the parent comment notes, is not really helpful to the experienced programmer.

As a hobby project I'm currently working on a replacement for web2c, the nightmarish program written in the 1980s that is used to translate the TeX source code -- written in WEB -- to C. And I must admit that I don't really like WEB. It is quite difficult to parse correctly, since the tokenizer to some degree needs to cover TeX, Pascal, and WEB and is not regular (there e.g. are nested comments), and the WEB macro system relies on applying text substitutions and reparsing the entire file until no further substitutions can be applied, which might be nice from a theoretical point of view, but at least from my experience, is quite hard to implement. Even the C preprocessor -- which in my understanding is just a single feed-forward pass -- is sane in comparison to WEB.

You can set breakpoints in cweb. Knuth has even commented about liking that feature. :)

The magic of #line directives.

It does make me jealous of just how far we've regressed when it comes to debugging. I have almost flat out given up on stepping through code in most modern environments.