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

81–90 of 103 posts

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

#81

Post by chipsy »

thyrsus wrote: post #64
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 involv…

I used Leo for a solo game project - AS3 code - made over the course of about a year. I also took some notes with it during the same time. It was over five years ago now. I don't remember all the details of what I did, but:

First of all, there were some encoding conflicts that were introduced when mixing Leo with other editors. When I go back to the project now, it doesn't compile because of the encoding errors. (It's fixable, I'm sure.)

Second, I had more classes than I needed. The secret to writing compact game code is - basically - to write few real classes and rely on plain old data and a large main loop. As it was, they were calling up and down some hierarchy, splitting pieces of the main loop into different classes, running a custom scripting language to drive AI, etc. I had all sorts of ill-considered ideas at the time and no real guidance. It wasn't a _tremendous_ amount of code(running a simple count again, 31,145 LOC with whitespace/comments and 22,372 without), and Leo documented what it all did, but the tool couldn't suggest why it was fundamentally rotten, it just added process on top. By the end I wasn't really using Leo, because it wasn't solving my problems.

Looking back on it now, I have a style that can more naturally accommodate a literary programming approach because I'm more likely to write a straight-line solution first. But I would not rely on an external tool again as I don't want the dependency.

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

#82

Post by klibertp »

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, why would it be bad in "normal" programming?

Instead of declaring LP as "too hard for normal people to use" we should try to teach people to be better writers. It's not necessarily one or the other, you can easily learn how to write prose (LP texts) along learning how to write code.

The only real problem with LP (besides lack of relevant skills in programmers) is ensuring that comments and code are in sync. But, how is it worse than the situation with documentation we have now? If anything LP makes it easier to keep docs and code in sync: they are in a single place and you can alter both simultaneously.

Of course, LP is a fuzzy concept. For example I call a certain style of writing comments LP, while others say that you need to have a tool like CWEB and the like to do LP. What's important is the push towards making the code more understandable by humans. There are different techniques to this end and LP is one of the more powerful among them.

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

#83

Post by toothbrush »

gargarplex wrote: post #36

Whenever I'm on a team and I get the opportunity to do code reviews, I strongly encourage it to reduce the Bus Factor

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

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

#84

Post by mrob »

greenyoda wrote: post #38
minopret wrote: post #37

Earlier quoted context omitted.

Which wiki engine do you have in mind? There certainly is revision control in MediaWiki, Confluence, and others. Granted, I wouldn't use those in place of a source code revision control system such as git. There are generally no "annotate"/"blame" or "pickaxe" features. I would agree with writing something code-friendly in the first place, examples of which would include DocBook and Restructured Text.

There's at least one wiki that's built on top of Git: https://github.com/gollum/gollum

There's also Gitit, which supports multiple VCSs including git:

https://github.com/jgm/gitit

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

#85

Post by toolslive »

geocar wrote: post #66

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 litera…

the code already explains in all details _what_ it does. the comment should just tell you the _why_.

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

#86

Post by klibertp »

lexicality wrote: post #79
daly wrote: post #44

I've been using literate programming for 15 years on many projects. The largest and most visible one is Axiom ( https://en.wikipedia.org/wiki/Axiom ) which currently has many thousands of pages with embedded code. I've talked to Knuth. He claims he could not have implemented MMIX without literate programming. Literate programming is really valuable but you only understand that once you really try it. I gave a talk on…

> 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.

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

#87

Post by 1arity » 

  pushl INHIBITIONS
It did. It's called culture. You just didn't realize all the ways it programmed your biases and perceptions.

Why?

Because it was so successful.

Computer programming, by contrast, is so explicit and obvious. The subtlety is lost. And with it, our humanity ( and ability to be subtly manipulated by forces beyond our comprehension and below our level of conscious perception ! ).

Culture is the original literate programming language. Instruction pointer for the collective mind. Virtual machine of choice ? Books. And your reading of them.

  popl INHIBITIONS

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

#88

Post by gargarplex »

toothbrush wrote: post #83
gargarplex wrote: post #36

Whenever I'm on a team and I get the opportunity to do code reviews, I strongly encourage it to reduce the Bus Factor

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

Haha :)

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

#89

Post by klibertp »

hzhou321 wrote: post #41

First of all, what do we think is literate programming? * Is it just interspersing documentations with the code? * or Is it an idea of writing code in the style of communications? There is subtle difference. The former is writing code first, then write documentation to explain the code (without changing the code significantly). For the latter, one may still write code, but he is not writing the code just to get compu…

> who, after spending so much effort get the code written and debugged and barely worked, still have the energy to write article to explain it

Professionals who care about long-term success of a project?

Most of what I see in this thread are just excuses, born out of either ignorance or laziness. Or both. The same arguments that were used against adopting higher level languages instead of asm.

The truth is, as sklogic says in this thread, the code won't ever tell you the whole story. You're not writing code in a vacuum, you have Jira tickets, requirements, mockups and so on to help you. Yet people throw these away and leave only the code, as if working with code alone was what they do and what should be done.

I wish programmers stopped being like that. They should just learn how to write ok - not great, just ok - prose and get it over with. It's so frustrating to see programmers reject good ideas because of laziness and dumb stubbornness. I'm starting to believe that it's just the human nature at play here. Makes me hate humans even more than I already do.

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

#90

Post by WorldMaker »

gldnspud wrote: post #40
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…

Your mention of commit messages resonates strongly with my own professional experiences, and I'm sure with many others' as well. Several months ago I started working with a commercial code base that has about 3 years of commits and over a dozen contributors, but very few inline comments. Navigating and refactoring it is usually a fairly reasonable process due to well-named symbols, module organization, and test cases…

I've been accused of not writing enough comments in the code itself and then writing "novels" in the commit messages and "Literate Revision Control" is probably the best name for that sort of style. It's very easy for comments in the source to grow stale, but the commit messages mostly (our source control tools still aren't perfect with regards to moves/refactors) tell the story over time and mostly show only relevant commit information, with "stale" commit information falling away into history/legend/myth as its code gets rewritten and retouched.

I've been liking how Visual Studio's CodeLens (now available in cheaper SKUs in 2015) brings focus to commit history specific to logical units in the code (methods and classes).

Now I'm curious where you might be able to push things if you purpose built a "Literate Revision Control" tool and what sort of strong "epic poem" style of commit messages would best produce useful "novelizations" of a codebase...

Post reply on HN