Would love insights from people who used literate programming on non trivial projects.
Ask HN: Why did literate programming not catch on?
1–10 of 103 posts
Re: Ask HN: Why did literate programming not catch on?
#2I 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.
Re: Ask HN: Why did literate programming not catch on?
#3Because 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 of date as the software evolves to fit new requirements. 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.
Re: Ask HN: Why did literate programming not catch on?
#4Because 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…
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 in a wiki but since it lives far away from the code, those things dont get used as much as I would like. Being able to add written reference material in a file along with the code and then having the ability to see a code only view seems appealing from where I am at currently.
Re: Ask HN: Why did literate programming not catch on?
#5I 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.
Besides, literate seems to go against the current view of overcommenting as an anti-pattern.
I don't have a dog in this fight one way or the other, but something about this statement irks me. I can't help but think "so what?". That is to say, Literate Programming either is a good idea, or it isn't. The answer to that question is orthogonal to "the current view" of whatever. Communities have had majority held opinions which were wrong on plenty of occasions. If one is going to question whether or not to use LP, shouldn't they analyze it on it's own, and not simply accept pre-existing biases?
Re: Ask HN: Why did literate programming not catch on?
#6Because 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…
"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 code that are critical (e.g., low-level APIs), but that nobody has worked on in a year.
Also, while startups may have smaller code bases and thus have less problems with these issues, successful startups eventually do become larger, established businesses with huge legacy code bases (think Google or Facebook). At some point, lack of accessible knowledge about how the code works can grow into a massive technical debt. (Been there, done that, regretted it.)
Re: Ask HN: Why did literate programming not catch on?
#7Because 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…
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!
Re: Ask HN: Why did literate programming not catch on?
#8Because 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…
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…
Maybe to get the wiki closer to the code, you could put links to relevant wiki pages in your code comments. Some editors even recognize URLs in the code and allow you to click on them for instant access. And if your code repository is HTTP-accessible, you could put links to your code on your wiki pages.
Re: Ask HN: Why did literate programming not catch on?
#9I 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.
Besides, literate seems to go against the current view of overcommenting as an anti-pattern. I don't have a dog in this fight one way or the other, but something about this statement irks me. I can't help but think "so what?". That is to say, Literate Programming either is a good idea, or it isn't. The answer to that question is orthogonal to "the current view" of whatever. Communities have had majority held opinions…
The question was "why didn't?" This was my speculative guess.
It seems plausible to me (total guess again) that people who consciously minimize comments would not be inclined to literate programming, since if you're consciously minimizing comments, what's left to literate anyway? My guess.
And no, I don't have a dog in there either, not the least because I've never seen anyone use literate programming in the same building I was in.
Re: Ask HN: Why did literate programming not catch on?
#10Because 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…
"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 and are sitting on a beach somewhere), it just sucks.
The thing is - being eclipsed by a faster, nimbler competitor who steals your market is a bigger problem. Bad code will make your programmers groan and occasionally threaten to quit, but it usually won't threaten the existence of an organization. A bad product will threaten the existence of an organization. So among surviving companies, code generally tends toward shitty, because the ones that spent a lot of time on code hygiene often went under during the growth & competition phase of the industry.