5 ms·

My main problem with literate programming is that it is difficult enough to keep short comments up to date vis-a-vis the code they describe. Longer comments wou

My main problem with literate programming is that it is difficult enough to keep short comments up to date vis-a-vis the code they describe. Longer comments would be even worse. I also suppose the modern equivalent of this, in many use cases, is a Jupyter notebook.

Chris_Newton 10y ago
My main problem with literate programming is that it is difficult enough to keep short comments up to date vis-a-vis the code they describe. Longer comments would be even worse. Perhaps counter-intuitively, I have found the opposite to be the case so far. It’s all too easy to overlook a couple of small comments out of 20 when you update a screenful of code. You can’t really miss a whole paragraph of text that separates a few lines of code you’re working on from everything else. I’ve also found that with literate documentation the emphasis is naturally on explaining the big picture and why things are being done, and that kind of information tends to remain relevant through minor code changes anyway. You can still add short comments about particular points in the code as well, and maintaining those is much the same whether you’re using literate programming or not.
e12e 10y ago
Ah, but in literate programming, the challenge is to make sure the code matches the narrative, not the other way around. > I also suppose the modern equivalent of this, in many use cases, is a Jupyter notebook. Yes - and no. I think when you're writing a document (or working up to a document) - such notebooks will naturally tend toward lp. This our data, here are our cleanup procedures. This can be visualised like so. Thus we can conclude... Etc. I wonder if lp would catch more on if there was more prose classes given to cs students? afaik most "professional" writers will do a top-down like design; lay out plot elements, fill in chapters. It's how you can write a good book in less than a year. I've seen many authors say that their first book was really slow going, but then as they get better at the craft of writing, they write quicker and better. I've always found the "top down" design for small programs to be intuitive. They are often: setup, get parameters/configuration, read data/do stuff, clean up. I think forcing oneself to write a sentence or two for each (no code!), sets one up for success with the first draft. A complement to BDD/TDD in a way. Similar to how explaining something to someone else is a great way to learn it better.
akkartik 10y ago
Yes, if it seems to require a lot of prose, I think you're doing it wrong. See my comment at https://news.ycombinator.com/item?id=12051069 https://news.ycombinator.com/item?id=12051069 for how it can be far more powerful than a notebook.

Chris_Newton 10y ago

My main problem with literate programming is that it is difficult enough to keep short comments up to date vis-a-vis the code they describe. Longer comments would be even worse. Perhaps counter-intuitively, I have found the opposite to be the case so far. It’s all too easy to overlook a couple of small comments out of 20 when you update a screenful of code. You can’t really miss a whole paragraph of text that separates a few lines of code you’re working on from everything else. I’ve also found that with literate documentation the emphasis is naturally on explaining the big picture and why things are being done, and that kind of information tends to remain relevant through minor code changes anyway. You can still add short comments about particular points in the code as well, and maintaining those is much the same whether you’re using literate programming or not.

e12e 10y ago

Ah, but in literate programming, the challenge is to make sure the code matches the narrative, not the other way around. > I also suppose the modern equivalent of this, in many use cases, is a Jupyter notebook. Yes - and no. I think when you're writing a document (or working up to a document) - such notebooks will naturally tend toward lp. This our data, here are our cleanup procedures. This can be visualised like so. Thus we can conclude... Etc. I wonder if lp would catch more on if there was more prose classes given to cs students? afaik most "professional" writers will do a top-down like design; lay out plot elements, fill in chapters. It's how you can write a good book in less than a year. I've seen many authors say that their first book was really slow going, but then as they get better at the craft of writing, they write quicker and better. I've always found the "top down" design for small programs to be intuitive. They are often: setup, get parameters/configuration, read data/do stuff, clean up. I think forcing oneself to write a sentence or two for each (no code!), sets one up for success with the first draft. A complement to BDD/TDD in a way. Similar to how explaining something to someone else is a great way to learn it better.

akkartik 10y ago

Yes, if it seems to require a lot of prose, I think you're doing it wrong. See my comment at https://news.ycombinator.com/item?id=12051069 https://news.ycombinator.com/item?id=12051069 for how it can be far more powerful than a notebook.