Ask HN: Why did literate programming not catch on? • Hacker News Board

Re: Ask HN: Why did literate programming not catch on?

#61

Post by RobertBlair » Mon, Aug 17, 2015, 6:57 AM UTC

nickbauman wrote: post #39

Literate programming tries to make every line of code traceable to English (or some other natural language). It's as hard as writing the same program twice in two languages. Perhaps harder: one is for programming a modified lump of sand. Another is for programming humans. The latter is a lot harder to do well than the first. Then the question becomes: which one is correct? Maybe it's just easier and cheaper to write…

You don't get it Nick - that lump of sand doesn't understand your code at all.

It only understands the machine code emitted by the run-time engine (assuming Java/Python etc here).

The language you write in has been developed, at enormous expense, to allow you to express your logic, in a way that you, a human, can understand.

If it were not necessary for you (or other developers) to understand the code, then high level languages would not be needed.

In short, you have got it exactly barse-ackwards: the programming language you use is for humans - and only for humans.

The only reason it is apparently "hard" has nothing to do with computers, and everything to with the inescapable fact that correct, consistent and reproducible logic patterns are hard.

I respect Donald Knuth very highly, but in that literate programming thing he is wrong - it is the code itself that must be clear and readable. Accuracy comes second, efficiency is third and 'elegance' is dead last. IMHO.

Re: Ask HN: Why did literate programming not catch on?

#62

Post by qznc » Mon, Aug 17, 2015, 7:04 AM UTC

kazinator wrote: post #49

TeX benefited from literate programming because it was written in a higher level assembly language. (Also, it was written by someone who liked to write books, and if a book was about software, he wanted to integrate the writing of the book and the software.) Better than literate programming is to write code that explains itself. Don't write two things, one of which executes and the other explains it; write an explana…

Knuth wrote TeX in Pascal.

Are you talking about MMIX as "higher level assembly language"? MMIX is the (a?) programming language used in TAOCP. For Knuth it was a purely theoretic thing. Other people have implemented MMIX by now.

Re: Ask HN: Why did literate programming not catch on?

#63

Post by rndn » Mon, Aug 17, 2015, 7:12 AM UTC

This question was also brought up on reddit a while ago: https://www.reddit.com/r/compsci/comments/1zrujz/literate_pr...

My pet theory is that programmers are driven by a constant feeling of obsolescence: Most implementations are incredibly short lived so that it seems futile to optimize the code for understanding (literate programming), when much less (programming experience, comments and help by people who know the code base) is good enough. Especially the last point in parentheses is crucial: Asking someone who knows the code base is likely a more efficient superset to text, because asking can be selective, nuanced and individual while a text just stares back at you.

Re: Ask HN: Why did literate programming not catch on?

#64

Post by thyrsus » Mon, Aug 17, 2015, 7:16 AM UTC

chipsy wrote: post #17

It makes it harder to make changes. The story you start telling is not what you end up with later, after you've completed all the non-trivial features and major assumptions have fallen through. Going back and fixing the story as you go along is expensive. Writing the story after it's done is too late - the business value is in the product's shipped functionality, not in the development artifacts. We have an alternate…

I'm fairly happy with Leo for "documenting" my Puppet nodes - I create a Leo node for each Puppet node or node regex with a link to the node definition, and a link to the "documentation" node of each class included for that node. Classes have "documentation" nodes which similarly link to their definition, files and templates and to documentation nodes of any classes included by the class. There's no more prose involved than you'd expect in-line. I find the structure extremely useful to re-discovering how a particular node is configured. If there are simplifications available, I find the structure makes them visible.

Perhaps the above would be less useful for more traditional code. Could you describe in more detail how you used it?

I have a long catalog of improvements I'd like to see made to Leo (e.g., its XML file format is version control hostile - try resolving merge conflits on several thousand lines of deeply nested machine-targeted XML; or try sending a pull request slathered with "sentinels"). Building such tools being out of scope for my day job, my re-imagined version won't be available any time soon.

Re: Ask HN: Why did literate programming not catch on?

#65

Post by bandrami » Mon, Aug 17, 2015, 7:22 AM UTC

dthal wrote: post #18

It does survive, in a certain sense, in scientific programming and data science. Both iPython notebooks and Rmarkdown are a sort of literate programming, although with the emphasis on the text more than the code. In that setting, the executable artifact is not really more important than the explanation of why the code does what it does, so the extra overhead is justifiable. Rmarkdown example: http://kbroman.org/knitr…

The "notebook" paradigm in Mathematica is another good example; arguably it's as much a part of the experience as the underlying Wolfram kernel.

Re: Ask HN: Why did literate programming not catch on?

#66

Post by geocar » Mon, Aug 17, 2015, 7:30 AM UTC

Programmers often say comments are for describing algorithms -- especially hairy ones, but it's a straw man: The code does what it does, and the comment doesn't enter into it. If anything the comment can confuse because programmers don't usually read code, but can find it easy to agree with the comment so they move on.

I think that the decision to bring code into this world is not one to be taken likely, and a literate program is simply the story of why interwoven with the implementation of what: Where did -2 come from? When I ifdef for a FreeBSD bug, how will I know if the bug is fixed (and the code can be removed/changed?) And so on.

Literate programming isn't the only "solution" to this problem. Making programs really big by duplicating efforts, and working around workarounds, using Java seems to "work" (for strange values of work), so perhaps this is a blub thing? If your code is "self documenting" then you don't know what documentation is.

That is to say: Literate programming didn't catch on because it was dismissed by the larger number of programmers who could get "things done" who didn't understand literate programming.

Re: Ask HN: Why did literate programming not catch on?

#67

Post by trhway » Mon, Aug 17, 2015, 7:44 AM UTC

there are marble towers and there are dirty trenches. There are only few things that are efficient and matter in the trenches. Putting beautiful marble on the trenches' walls just isn't one of them.

Re: Ask HN: Why did literate programming not catch on?

#68

Post by sklogic » Mon, Aug 17, 2015, 7:48 AM UTC

chipsy wrote: post #17

It makes it harder to make changes. The story you start telling is not what you end up with later, after you've completed all the non-trivial features and major assumptions have fallen through. Going back and fixing the story as you go along is expensive. Writing the story after it's done is too late - the business value is in the product's shipped functionality, not in the development artifacts. We have an alternate…

It depends on your programming style. If it's a typical convoluted, constantly refactored OO code - then, yes, literate programming won't help.

If your code consists of a lot of DSLs, clearly separated from each other, each implemented in a small, compact, readable module - then you won't have to change that much in the existing code. In my experience this style is a very good match for a literate programming.

Re: Ask HN: Why did literate programming not catch on?

#69

Post by sklogic » Mon, Aug 17, 2015, 7:51 AM UTC

erikpukinskis wrote: post #51

I've been trying to write a JavaScript framework in a literate way for a year or so, here's what I've found: * I end up deleting most of the prose once the code starts getting good. Good code is sort of literate already. * As others have said, when you're doing some code churn, it's difficult to maintain a narrative structure that makes sense. * Existing frameworks, at least for web programming, encourage you do draw…

Code itself does not tell the story, does not give you any background or any non-formalised constraints. There is absolutely no way code can replace a proper literate prose.

Re: Ask HN: Why did literate programming not catch on?

#70

Post by ucho » Mon, Aug 17, 2015, 7:53 AM UTC

ecthiender wrote: post #11

greenyoda wrote: post #6

Earlier quoted context omitted.

"Most real-world products face new requirements on a weekly, sometimes hourly basis; as a result, most fast-growing startups have oral cultures where the way to learn about the software is to ask the last person who worked on it." The weakness of this approach is that the last person who worked on some piece of code may be that guy who quit last week. Also, once you have a big code base, there may be parts of the cod…

But isn't the point of literate exactly that? You keep your code and your docs (design, description etc) closely knit. So even if you need to change your software rapidly, you change your code and docs together. PS: I'm trying to do literate for my full time programming, still trying to cross the hurdle.

> keep your code and your docs closely knit

It is hard. Most people I know try to replace comments with very descriptive variable and method names - that are easy to change in any IDE. On the other hand comments (and other docs) sooner or later turn into misinformation/lie, unless you have very disciplined developers, all of them.