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

51–60 of 103 posts

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

#51

Post by erikpukinskis »

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 boundaries around individual homogenous chunks of one type of code (router, view, migration) rather than human conceptual concerns (upload a file, browse my photos, etc). In order to do a good job explaining what a view does, you need to know what the controller is providing. In order to understand that you need to understand what the domain layer is doing. Frameworks just make it really hard to put, in one file, everything necessary to explain a concern.

I still believe in the idea, but I think for literate programming to work well it has to be done in an ecosystem where the APIs are all structured for literate programming, which doesn't really exist (yet).

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

#52

Post by thangalin »

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 Pander R package renders objects into Pandoc's markdown. This allows you to generate a wide variety of output formats, including ConTeXt or LaTeX documents (and subsequently PDF).

http://rapporter.github.io/pander/

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

#53

Post by No1 »

nostrademons wrote: post #10
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…

All of those are problems in practice. For some, there are mitigating effects, eg. many companies use code reviews or pair programming to ensure that there are multiple eyes on each section of code, or they rotate out tasks between programmers so that multiple people need to get familiar. For some (eg. the large codebase that got big but has no documentation, and all the original authors have cashed out their options…

> Bad code will make your programmers groan and occasionally threaten to quit, but it usually won't threaten the existence of an organization.

You're joking, right?

I have seen companies be "eclipsed by a faster, nimbler competitor" because they have a crappy codebase.

The reason for the implosions were that, "during the growth & competition phase of the industry," they could not grow because new developers really could not ramp up on the crappy, woefully-undocumented codebases, whilst clients left for less-buggy products that were adding new features.

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

#54

Post by a3n »

EliRivers wrote: post #22
a3n wrote: post #2

I always liked the idea, but it seemed too indirect to me. Software is hard enough as it is, without adding yet another hurdle to get from brain to .exe. IDE's are probably the best middle ground, as they "know" enough about your code to help you find the parts you want. Besides, literate seems to go against the current view of overcommenting as an anti-pattern.

Software is hard enough as it is, without adding yet another hurdle to get from brain to .exe In my experience, it ultimately made it easier (see my big comment somewhere else here). It wasn't an obstacle to getting it done; it forced me to do what I really always knew I should - think about the design, make sure it made sense. Your comment also suggests that you might have missed a key point; it's not for you. It's…

> Your comment also suggests that you might have missed a key point; it's not for you. It's for other people (and also yourself in the future

Most of the code you write over the years will be thrown away, sometimes before it's even released. So who is that text or literate comment for? :)

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

#55

Post by taeric »

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 love the comment of "defending against complexity by adding more." That defines a lot of the tricks we use in every day programming to defend against complexity.

I also love the juxtaposition of this comment and the other top comment.

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

#56

Post by eikenberry »

I find that literate programming is something of a code smell. If a program is so complicated that it requires that much commenting, something went wrong during the design process. The program should be the most concise and clear description of what is going on. That is the point of writing a program, to describe the problem to other developers.

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

#58

Post by laichzeit0 »

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…

> Consider it to be the standard of excellence that you expect from a professional programmer. Then decide to be a professional and hold yourself to that standard.

Whilst I haven't read Physically Based Rendering, I had the same illuminating experience reading C Interfaces and Implementations: Techniques for Creating Reusable Software by Hanson which was also written in the literate programming style.

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

#60

Post by angersock »

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…

Companies should hire language majors, make them Editor-in-Chief, and put them on every programming team. Nobody checks in code until there is at least a paragraph that explains WHY this code was written. Anybody can figure out WHAT it does but reverse-engineering WHY it does it can be hard.

And those companies will get their lunches eaten by folks who know that you can do well enough simply by throwing bodies at the problem, unfortunately.

Post reply on HN