Live data from Hacker News

Ask HN: Why did literate programming not catch on?

news.ycombinator.com

21–30 of 103 posts

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

#21

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…

The only thing worse than a big system with no documentation is a big system with documentation that is full of lies and untruths. Short of hiring people full-time to write documentation, and to ensure that all changes to the program are done in a heavyweight-enough process to ensure that documentation changes match the programming changes, those are your two choices.

A not as big system decomposed into well-defined parts with clear and concise documentation is best of all. Great documentation hits many purposes including lessening learning curve for training and behavior qualtitative verification without burdening readability by mindlessly duplicating boilerplate that detracts.

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

#22
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 for other people (and also yourself in the future - I have certainly come back to my own code a year later and wondered what the hell I was doing). It's to help them understand what you've done; a small amount of extra burden on you now to remove a large burden on other people in the future.

It made the design modular and easy to follow, without having to read the code to work out what each section was doing. When I wanted to understand someone's design, I read the design bits. When I wanted to dig into the actual code doing something, I followed the chunks down from the design level into the exact section of code meeting that part of the design.

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

#23
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…

I just wanted to note that this isn't some newfangled invention, Mathcad did interactive notebooks in 1986.

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

#24
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…

[deleted]

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

#25
There are two parts to literate programming. One is the style of commenting and structuring the code, which makes it easy for humans to follow. The other part is the tooling you use when you want to write literate programs, which includes what syntax you use for defining blocks and how do you tangle/weave your code.

There are many tools which support Literate Programming for many different languages. The usual reservation about additional tools applies: each member of a team needs to have it installed, build times get longer, time for a new programmer to start contributing gets longer and so on. It makes many people never even consider LP.

But, it's important to remember, that the tools you use are just an implementation detail. What's important is an idea that source code should be written to be read by humans, not only for computers to execute.

Sometimes there's a need to go over a piece of code with a colleague who doesn't know it. It happens a lot when a new programmer joins a project that has some code written already. This is because to understand the code you need to know the context it was written in. The problem is that programmers often don't document this context enough (or even not at all). This means that reading the code is essentially a reverse engineering someone's thought patterns. It's much more efficient just to sit next to the person and assist him in reading the code by providing a live, context-aware commentary.

LP is "just" that commentary written directly in the code. What's important is that you don't need any special tools to use this style in your comment if your language is flexible enough. Most dynamic languages nowadays are capable of supporting LP style. Don't take my word for it, see for yourself. You can just go and read some LP code. A couple of examples:

   http://underscorejs.org/docs/underscore.html
   http://coffeescript.org/documentation/docs/grammar.html
   http://backbonejs.org/docs/backbone.html
As you can see it's a plain JS (or CS). The pages were created with "docco" tool, but you can read the source with most of the same benefits (excluding rendering of maths symbols, which docco doesn't support anyway).

To sum up: LP is not dead, it just changed its form a little. Many people adopted (or invented independently) this style of code structuring and commenting. Many real-life codebases are written in a literate style because it makes a real difference on how long it will take for someone new to grok the code. Such codebases use docstrings and other mechanisms available in the language to do exactly the same thing that previous LP implementations did.

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

#26

Because software changes so rapidly. Literate programming is based on the idea that you should explain what software does and how it does it in detail so that a reader can follow along and learn. That works great for TeX, which hasn't changed significantly since 1982. It works less great for say, Google/Alphabet, which wasn't even the same company last week. The general problem with documentation is that it gets out…

Because software changes so rapidly.

I imagine you’re right in practice, but one might also ask whether code that is changing faster than understanding is changing too fast. It’s not as if mechanically updating literate-style documentation to reflect a change should be disproportionately expensive compared to making the change itself, or to making corresponding changes to test suites, getting the code reviewed by other people, or getting the changes merged into source control.

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

#27
The fewer comments the better. Code is constrained by the programming language, since it must be executable. But there are no such constraints on prose. While Knuth may adorn his code with extremely illuminating prose, unfortunately the same is not true for many other programmers.

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

#28
post #4

Earlier quoted context omitted.

That is a good point. Reason I was asking this question is because of my current workflow. The workflow looks has the following stages - Stage 1. Read a bunch of papers and blogs for the problem being solved. Stage 2. Assimilate relevant ideas and come up with some kind of design. This stage usually involves hand written notes, doodles etc. Stage 3. Write code based on the design. I currently document stages 1 and 2…

Since you are doing stage 1 and 2 on a computer system, you could go on, and write the code of stage 3 in that very same wiki too! Then write a spider to scan this wiki, extract the code blocks, and assemble a compilable program, and you're done, wiki literate programming!

A wiki is a terrible instrument for writing software documentation. For example, there is no revision control to track changes as required by by changes in the code, there is much duplication. I could go on, and on, why a wiki is not optimal for any documentation associated to a software project.

Better to use a system like DITA or dockbook.

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

#30
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…

Thanks, this was useful.
Post reply on HN