Hacker News Reader

Comment by BeetleB | Hacker News Reader

The problems one will run into with literate programming:

1. Lack of tooling.

2. Refactoring becomes nontrivial

3. How one would write a program in literate style will vary widely from person to person. If you write your code in literate style, it may be easy for you to follow it years later and modify it, but it likely will not be the case for a coworker. If they have to modify the code, the cognitive load will not be too different from that of just dealing with well written code.

Disclaimer: I've written two nontrivial programs literate style that I continue to rely on and occasionally modify years after writing them. It works as advertised.

View on HN

For point 3. - it's exactly the same with code that's not literate. Writing code is ultimately about expressing ideas using a language, which is really much closer to writing a novel than to drawing a plan for a bridge. As such, if you want to make your code understandable to other, you have to learn to write well. Just like with novels, there's no problem with having a personal style, or a specific flavor that comes from how you use the language, how you structure your sentences and paragraphs, how you guide a reader through the story.

In other words, the style varying between people is not a problem - bad writing is. And, unfortunately, in my experience very few programmers are capable of consciously producing good writing. The fact that most of the docs out there are barely-legible trash is a proof of this.

I'm sure that reading literate code from Charles Stross would be a blast. It would be exciting, sometimes surprising, but still clear, easy to navigate, structured in a way allowing for extension within a well thought-out framework. Unfortunately, when people without his talent try to use LP, they produce things on par with that unfinished fantasy novel you started writing in 8th grade.

Programming requires a bit of talent, but you can get by with lots of hard work. Literate programming is much harder than that and requires a lot of talent to be beneficial to the codebase. Without that, your LP code will be Fifty Shades of Twilight, and honestly, we don't need more of things like that.

It's a nice perspective, but the fact that more people have read Fifty Shades/Twilight than the sum total of all who have read any of Charles Stross's works undercuts your point.

And while you add to point 3, it wasn't my main point.

Take any two exceptionally good writers who have very different styles. If one of them produces literate code, the other may be able to understand it very well, but it is unlikely that he can modify it, along with the prose, and maintain the quality of the literate document.

It's not just about bad writers, but incompatibly good ones.

I believe you're wrong - writers can, and do, steal styles and ideas from each other all the time. Not to mention, the editors are basically doing this:

> can modify it, along with the prose, and maintain the quality of the literate document.

for a living. As long as you're accomplished enough of a writer, you'll be able to analyze the works of others and copy them easily. It's coming up with your own style that's a problem.

To summarize: exceptionally good writers will be able to modify and expand each other's work without much effort. Or at least that's what I believe, based on some personal experiences with writing and writers. It should be quite similar with literate programming, too.

Doubt u get what beetle said. It is far more work to rewrite an essay with a different thesis.

Obviously. But we're talking about modifying the existing text, not rewriting it. How often do you have a chance to redo a whole project with completely different implementation and/or completely changed requirements? In my experience, most of the programming work is about adding new chapters to the existing text, and editing the existing text in some areas to make it easier to reason about. In other words, it's either extending the existing functionality, or refactoring it. It's not about rewriting the whole thing.

I would be happy to know, how experienced are you with actually writing creative works, working with a text, working on editing it, and so on? Again, I'm not 100% sure if literate programming would be exactly the same, but if it is similar to creative writing, then - I stand by this point - personal style of writing is not a problem. For two reasons:

- it's trivial to adjust your writing to an existing style when doing light editing and small extensions

- it doesn't matter if different stories in an anthology are written in different styles (actually, you buy anthologies because of different styles), so big extensions and rewrites in a different style are also ok

I feel like problem 1 is on the cusp of solutions given the amount of money poured into tooling for "notebooks" like Jupyter. Notebooks are a form of literate programming. Projects written in Jupyter Notebooks are getting larger and scaling harder. I think a convergence should eventually happen that larger scale literate programming tasks can benefit immensely from the tooling investments in notebooks like Jupyter.

Problems 1 and 3 I could imagine. I would need to learn how to be a better writer to share a literate program.

As someone experienced in the topic, What's the biggest hurdle when trying to refactor the code?

> What's the biggest hurdle when trying to refactor the code?

I'd guess it's updating cross-references in prose and rewriting chapters of documentation which no longer make sense after your refactoring.

I'd also say that a lot of the reason for refactoring is just... different. Literate programs are typically made to be fairly self contained works. If you have some general purpose code that is of use in the entire codebase, you can make that its own section and cover it when it is needed. Otherwise, you likely won't reach for the same coding strategies that are common outside of literate code.

I'm trying to find a way to describe this a bit better than the above. I think the easiest way to think about it, is that in most software projects you have a separate document that is the general architecture of the software. It is rare that you will need or want to refactor the architecture, so you try to keep that somewhat faithful to what the code is doing. In literate software, that high level architecture view is part of how you organize the code.

Refactoring becomes the dual problem space of both programming and editing.

It's simply more work - but that "more work" is vitally important, tedious, and resistant to any kind of automated help.

With Emacs org-babel I just do the refactor using the normal tools for whatever language on the tangled files and then detangle it back to the literate document. There's no problem here.

By "editing" I didn't mean editing the source. I meant the writing process, editing [0]. The thing you may hire an Editor to do. It is not something that you can automate, and the difficulty has very little to do with the tooling.

A slight change in code structure, may require many hundreds of adaptions to the literate document, for example.

[0] https://www.postgraduate.uwa.edu.au/__data/assets/pdf_file/0...

Reply on news.ycombinator.com