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

Ask HN: Why did literate programming not catch on?

news.ycombinator.com

Post reply on HN
Print view View original

91–100 of 103 posts

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

#91

Post by hirundo »

It did catch on, just in a different form. Our web shop is fairly typical of that. We do this with a combination of the Tomdoc (tomdoc.org) documentation specification plus Rubocop (github.com/bbatsov/rubocop) and peer review for enforcement. We use rubocop to ensure that methods are short and simple, and every such method that is public is accompanied by a tomdoc section. The result is that there are about twice the number of lines in our code file that are targeted at humans than computers. We generate separate documentation by extracting the tomdocs that has proven useful in explaining the code to the uninitiated.

However, to the initiated it's mostly in the way. With short, simple methods I find it easier to decode unfamiliar code by reading the methods than the by reading the tomdocs. Like many of my cow-orkers I've configured my editor to hide the tomdocs in normal use. Writing tomdocs is a chore to be done immediately before delivering code for peer review.

That's probably the biggest weakness of literate programming: it isn't for the programmer responsible for that code, or even for that programmer a year later when she has forgotten much of it. It's more for the developer or designer that isn't fluent in the language, but still has to interact with it. Since the value to the actual coder is distant and indirect, while the work of producing it is immediate, it tends to be an early omission under any kind of stress. In our case it would disappear if not enforce by peer review.

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

#92

Post by cousin_it »

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…

> We have an alternate method of understanding how software developed, which is to look at revision control commits.

Yes! If your source code files, version control commits, code review comments on those commits, and bug discussion threads are all cross-referenced in a unified Web interface, many problems just go away. IMO it solves the same problems that literate programming was supposed to solve, but less intrusively and more reliably.

Also I agree that code organization is often a bit overrated. I really like linear "hack hack hack" code, even if it has a bit of copy paste, and dislike highly abstract OO soup. On the flip side, I happen to be fanatical about good naming, which is easier if the code is more concrete than abstract.

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

#93

Post by No1 »

collyw wrote: post #78
No1 wrote: post #45

Earlier quoted context omitted.

> 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 "Oral culture" - I like that euphemism. It's not disorganized, confused, poorly-planned, and glaring technical debt, no, it's "culture." > Most real-world products face new requirements on a weekly, sometimes hourly basis If your requirements are changing on an hourly basis, it's time t…

You must have a nice cushy well defined corporate job if you think that constantly changing requirements are something unusual.

Changing requirements are quite normal, but changing by the hour is just poor project management, no matter what the environment.

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

#94

Post by gargarplex »

gargarplex wrote: post #88
toothbrush wrote: post #83

Earlier quoted context omitted.

Just being pedantic here, but the Bus Factor is something that a benevolent manager would like to increase , right? :)

Haha :)

I'm slowly and intermittently reading rands's book Managing Humans.

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

#95

Post by mcphage »

sklogic wrote: post #77
mcphage wrote: post #42

This is just me, but when I read through the literate programming book, and the hundred or so pages of literate code resulted in a program that could be replaced with a line of bash script, I decided that writing the program succinctly was more important than writing a novel to accompany it.

Uhm, I write literate code exactly because my code is very compact so I can afford to dilute it with an equal amount of prose. And, yes, I still prefer to print the whole thing and work with a paper rather than in any IDE.

> I write literate code exactly because my code is very compact so I can afford to dilute it with an equal amount of prose.

That I can get behind. My concern with the example in the book was, it didn't matter how good the prose was, the program would be nowhere near as understandable as the one line of bash, just due to there being 0.1% as much code to understand. And I realize that it's not a meaningful knock against literate programming as a whole, it was a bad example that soured the idea in my head. It made me more concerned about succinct, understandable code, rather than seeing the prose as sufficient.

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

#96

Post by taeric »

klibertp wrote: post #86
lexicality wrote: post #79

Earlier quoted context omitted.

> Nobody is going be around to remember that the strange block of code is there to handle Palm Pilots. Unless someone puts a comment above it? Literate programming isn't the only method of documenting code.

You're essentially doing LP if you have enough high quality comments. It doesn't really matter what tool you use for this.

No, you really aren't. To the point that if you aren't going out of your way to represent the narrative flow of what you are writing, you are probably not going to see any benefit.

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

#97

Post by klibertp »

taeric wrote: post #96
klibertp wrote: post #86

Earlier quoted context omitted.

You're essentially doing LP if you have enough high quality comments. It doesn't really matter what tool you use for this.

No, you really aren't. To the point that if you aren't going out of your way to represent the narrative flow of what you are writing, you are probably not going to see any benefit.

Yes, you are ;-)

The thing is, as I wrote in the other comment, that "modern"(like Lisp, as someone noted ;-)) languages already allow you to structure the code as you see fit. You don't have to define (or even declare) functions before their first use in the file, you can easily extract any part of the code into a function or method and you can place it anywhere you want. There are many mechanisms available for threading the context through functions, which makes direct, textual inclusion simply not needed.

In short: for LP to work you need to organize your code a way you'd like to read it. Many languages are capable enough that they don't need third party tools for these.

And I assumed that you do it anyway, because there's no real downside for this in many languages. If you don't do it in a language which supports it - shame on you. If you do, then "enough comments" is the only thing you need for your code to begin being literate.

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

#98

Post by [deleted] »

klibertp wrote: post #97
taeric wrote: post #96

Earlier quoted context omitted.

No, you really aren't. To the point that if you aren't going out of your way to represent the narrative flow of what you are writing, you are probably not going to see any benefit.

Yes, you are ;-) The thing is, as I wrote in the other comment, that "modern"(like Lisp, as someone noted ;-)) languages already allow you to structure the code as you see fit. You don't have to define (or even declare) functions before their first use in the file, you can easily extract any part of the code into a function or method and you can place it anywhere you want. There are many mechanisms available for thre…

[deleted]

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

#99

Post by taeric »

klibertp wrote: post #97
taeric wrote: post #96

Earlier quoted context omitted.

No, you really aren't. To the point that if you aren't going out of your way to represent the narrative flow of what you are writing, you are probably not going to see any benefit.

Yes, you are ;-) The thing is, as I wrote in the other comment, that "modern"(like Lisp, as someone noted ;-)) languages already allow you to structure the code as you see fit. You don't have to define (or even declare) functions before their first use in the file, you can easily extract any part of the code into a function or method and you can place it anywhere you want. There are many mechanisms available for thre…

I used to feel this way. So, in large I want to agree with you. However, the syntactic affordances of languages doesn't really do this justice. In the same way that writing an outline of a novel is not the same as writing a glossary to go with it.

Basically, if there are any parts of the program that you would describe differently in conversation, then it isn't the same thing.

Now, I fully grant I am getting close to a scotsman argument. I also grant that this is not necessary to write bug free software. However, I do see them as different things.

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

#100

Post by nickbauman »

klibertp wrote: post #82
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…

> Maybe it's just easier and cheaper Easier, yes. Cheaper, no - with LP learning a new codebase takes much less time than usual. As someone else noted programmers tend to be less than proficient writers (to say the least). That's unfortunate. Someone else mentioned that he sees value in LP in the context of education. That's because LP does make understanding the code both easier and faster. If it's good in education…

> Easier, yes. Cheaper, no - with LP learning a new codebase takes much less time than usual.

Unless the program is different than LP work. Then, which is correct? The LP work or the program? It's been tried many times. It's been called the Rational Unified Process. It's been called Roundtrip Engineering. Not worth the extra cost.

Post reply on HN