Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What is “literate programming”? (2024)

pqnelson.github.io

Post reply on HN
Print view View original

51–57 of 57 posts

Re: What is “literate programming”? (2024)

#51

Post by WillAdams »

drpixie wrote: post #46

I always liked the idea of literate programming, but it never seemed to get a toe in the door. A good start would be just commenting code! Almost all the code I've looked into recently has been startling - the only comments are the licence boilerplate at the top of each file! I can think of only one product/library/package that was commented to explain what was happening. Go look at the source for a random package th…

List of Literate Programs published as books:

https://www.goodreads.com/review/list/21394355-william-adams...

The main website for this of course lists some resources:

http://literateprogramming.com/

most notably:

http://literateprogramming.com/adventure.pdf

(the source code of the venerable Colossal Cave Adventure re-worked as a Literate Program by Dr. Donald Knuth)

Re: What is “literate programming”? (2024)

#52

Post by cxr »

Jtsummers wrote: post #36

Perhaps the most prominent example of literate programming missed by the author: https://www.pbrt.org/ Physically Based Rendering by Pharr, Jakob, and Humphreys. Responding directly to a couple things the author wrote: > When programming, it’s not uncommon to write a function that’s “good enough for now”, and revise it later. This is impossible to adequately do in literate programming. It's not impossible in literate…

> It's not impossible in literate programming. There's nothing about LP that impedes this, I do it all the time. I have a quick obvious implementation (perhaps a naive recursive solution) and throw it in to get things working. I revisit it later when I need to make that naive recursive one faster (memoization, DP, or just another algorithm all together). It's no harder than what I'd do with an ordinary approach to programming.

Do you do it as literate program, which is to say, your text first expounds on a naive solution to the problem, and then later outlines for the reader the complete solution?

Or do you write one literate program, and then update the file containing the text of your program after you realize the better solution—no different from anyone writing conventional programs—thus thwarting the fundamental promise of LP (since the "why" of changes like that—and the absence of answers to those whys—is exactly what makes it such a battle to understand unfamiliar programs).

The author is very obviously talking about the first problem. Your comments and failure to elaborate strongly suggest you're doing the latter.

Re: What is “literate programming”? (2024)

#53

Post by Jtsummers »

cxr wrote: post #52
Jtsummers wrote: post #36

Perhaps the most prominent example of literate programming missed by the author: https://www.pbrt.org/ Physically Based Rendering by Pharr, Jakob, and Humphreys. Responding directly to a couple things the author wrote: > When programming, it’s not uncommon to write a function that’s “good enough for now”, and revise it later. This is impossible to adequately do in literate programming. It's not impossible in literate…

> It's not impossible in literate programming. There's nothing about LP that impedes this, I do it all the time. I have a quick obvious implementation (perhaps a naive recursive solution) and throw it in to get things working. I revisit it later when I need to make that naive recursive one faster (memoization, DP, or just another algorithm all together). It's no harder than what I'd do with an ordinary approach to pr…

I've done both.

> your text first expounds on a naive solution to the problem

That's not how every literate program is written, nor is it the entire purpose of literate programming.

> Or do you write one literate program, and then update the file containing the text of your program after you realize the better solution—no different from anyone writing conventional programs—thus thwarting the fundamental promise of LP (since the "why" of changes like that—and the absence of answers to those whys—is exactly what makes it such a battle to understand unfamiliar programs). [emphasis added]

I think you misunderstand LP. Keeping history is not essential to literate programming. Having a series of evolving programs from naive to fastest possible is not the point of LP. Having an explanation of the program with the code is the point of LP.

Sometimes that means leaving history, sometimes it means removing it. A literate program is not a dead program. It's a living object that can be edited and changed over time. Keep the elements that are essential to the text. If the naive version is clearer (often it is) then retain it so you can explain the more complex fast version as it relates to the naive version. If it has no explanatory value, then drop it. If you implemented something incorrectly, it's not necessarily worth keeping unless the wrongness of it has value in itself.

Re: What is “literate programming”? (2024)

#54

Post by [deleted] »

Jtsummers wrote: post #53
cxr wrote: post #52

Earlier quoted context omitted.

> It's not impossible in literate programming. There's nothing about LP that impedes this, I do it all the time. I have a quick obvious implementation (perhaps a naive recursive solution) and throw it in to get things working. I revisit it later when I need to make that naive recursive one faster (memoization, DP, or just another algorithm all together). It's no harder than what I'd do with an ordinary approach to pr…

I've done both. > your text first expounds on a naive solution to the problem That's not how every literate program is written, nor is it the entire purpose of literate programming. > Or do you write one literate program, and then update the file containing the text of your program after you realize the better solution—no different from anyone writing conventional programs—thus thwarting the fundamental promise of LP…

[deleted]

Re: What is “literate programming”? (2024)

#55

Post by [deleted] »

Jtsummers wrote: post #53
cxr wrote: post #52

Earlier quoted context omitted.

> It's not impossible in literate programming. There's nothing about LP that impedes this, I do it all the time. I have a quick obvious implementation (perhaps a naive recursive solution) and throw it in to get things working. I revisit it later when I need to make that naive recursive one faster (memoization, DP, or just another algorithm all together). It's no harder than what I'd do with an ordinary approach to pr…

I've done both. > your text first expounds on a naive solution to the problem That's not how every literate program is written, nor is it the entire purpose of literate programming. > Or do you write one literate program, and then update the file containing the text of your program after you realize the better solution—no different from anyone writing conventional programs—thus thwarting the fundamental promise of LP…

[deleted]

Re: What is “literate programming”? (2024)

#56

Post by d-lisp »

MrJohz wrote: post #50
Nevermark wrote: post #32

Earlier quoted context omitted.

> I find it weird to not be able to find linux source code and commentaries That one statement is a great concise explanation/motivation for "literate programming". Explanations with code, that explain code design choices, in a way that enables the code to be understood better, and the ideas involved to be picked up and applied flexibly to reading and writing other code. Another way to view it is: Developers are "com…

I think that statement is also a great concise explanation for why literate programming doesn't really work in practice. For something as complex as the Linux kernel, there is no single document that is going to explain the entire system to anyone who reads it. For a start, different people need different levels of explanation. Someone fresh out of a JavaScript bootcamp is going to need a very different guide to Linu…

"Linux Kernel for the self-conscious lifeforms" would definitely fit on my shelves .

Re: What is “literate programming”? (2024)

#57

Post by MaxBarraclough »

MrJohz wrote: post #50
Nevermark wrote: post #32

Earlier quoted context omitted.

> I find it weird to not be able to find linux source code and commentaries That one statement is a great concise explanation/motivation for "literate programming". Explanations with code, that explain code design choices, in a way that enables the code to be understood better, and the ideas involved to be picked up and applied flexibly to reading and writing other code. Another way to view it is: Developers are "com…

I think that statement is also a great concise explanation for why literate programming doesn't really work in practice. For something as complex as the Linux kernel, there is no single document that is going to explain the entire system to anyone who reads it. For a start, different people need different levels of explanation. Someone fresh out of a JavaScript bootcamp is going to need a very different guide to Linu…

> different people need different levels of explanation

> the further a person is from understanding how the Linux kernel works, the more iterative the explanation will need to be

Good points. Reminds me of how science is communicated. The target audience of a research paper is other researchers. If the target audience were broader, it would have to be more akin to a textbook.

Post reply on HN