3 ms·

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 t

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.

taeric 9y ago
I have tried several times to explain this idea. I almost think it should be called narrative programming.
LukeShu 9y ago
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.
- taeric 9y ago
  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?

taeric 9y ago

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

LukeShu 9y ago

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.

taeric 9y ago
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?