3 ms·

Underwhelming so far. Literate programming sounds good, but sometimes it's too much text and you want to quickly scan a few lines of code and guess what's going

by grok2 10y ago

Underwhelming so far. Literate programming sounds good, but sometimes it's too much text and you want to quickly scan a few lines of code and guess what's going on without reading that wall of text. I wonder if this is for regular programming or for occasional programmers (non-programmers really) to try "stuff" out.

jcheng 10y ago
Personally I find literate programming helpful not for simple programming tasks, but for really hard ones; if you can quickly scan a few lines of code and figure out what's going on, then you probably don't need it. But if it's the kind of code where I know even future-me is going to have a hard time understanding what I've implemented without copious comments, then I really like literate programming. And it's more than just a different notation for comments. I find it psychologically elevates the narrative in a way that makes it feel like at least equal to the code in importance, therefore I end up being a lot more thoughtful and deliberate in writing the narrative.
- grok2 10y ago
  For code maintenance I've long since given up on assuming the comments are correct and simply read code and try to understand what is going on (and maybe read the comments later to see if they correlate to my understanding of the code). Many times I see that when fixing code, people don't update comments and a few times I've seen the comment indicates good intentions, but the code doesn't live up to the intentions :-). But I do see your point about it for more complex programs and maybe more complex programs of your own (that a future you will have to maintain).
clusmore 10y ago
Maybe I've just never written anything difficult enough to benefit from it, but I also feel like literate programming would only slow me down. A programming language is a language, just like human languages. To me, literate programming would be akin to wrapping paragraphs of French with paragraphs of English to explain it. Sure, that might be helpful if you don't know French (well), but for people with decent competency it's redundant and just a distraction, and only likely to cause confusion when there is disagreement between the two. But the beauty of programming languages over human languages is that because machines need to execute them, there is no room for ambiguity. Ambiguity is not just bad for computers, it's bad for humans too - misunderstanding requirements is a huge cause for delay, bugs and dissatisfaction of customers. The downside of writing for machines rather than humans though is that there is also no need for explanation of purpose or assumptions, which is the only thing I still add inline comments for. But even then, these can often be expressed in the language, and where possible they absolutely should be. If your code assumes some property or invariant, assert it! Or use the type system or tests to state and verify it. This way, the assumptions are constantly re-validated automatically by your build system, so the second they no longer hold you will know to reassess the code in question. I hate maintaining old code written in a convoluted way with a comment explaining that the purpose is to improve efficiency, and then realising that the code in question is no longer a bottleneck and the efficiency is irrelevant. If literate programming helps me understand the convoluted code, great, but what I really want is something that helps me validate that it even needs to be so convoluted in the first place, and lets me know the second I can simplify it again.

by grok2 10y ago

jcheng 10y ago

Personally I find literate programming helpful not for simple programming tasks, but for really hard ones; if you can quickly scan a few lines of code and figure out what's going on, then you probably don't need it. But if it's the kind of code where I know even future-me is going to have a hard time understanding what I've implemented without copious comments, then I really like literate programming. And it's more than just a different notation for comments. I find it psychologically elevates the narrative in a way that makes it feel like at least equal to the code in importance, therefore I end up being a lot more thoughtful and deliberate in writing the narrative.

grok2 10y ago
For code maintenance I've long since given up on assuming the comments are correct and simply read code and try to understand what is going on (and maybe read the comments later to see if they correlate to my understanding of the code). Many times I see that when fixing code, people don't update comments and a few times I've seen the comment indicates good intentions, but the code doesn't live up to the intentions :-). But I do see your point about it for more complex programs and maybe more complex programs of your own (that a future you will have to maintain).

clusmore 10y ago

Maybe I've just never written anything difficult enough to benefit from it, but I also feel like literate programming would only slow me down. A programming language is a language, just like human languages. To me, literate programming would be akin to wrapping paragraphs of French with paragraphs of English to explain it. Sure, that might be helpful if you don't know French (well), but for people with decent competency it's redundant and just a distraction, and only likely to cause confusion when there is disagreement between the two. But the beauty of programming languages over human languages is that because machines need to execute them, there is no room for ambiguity. Ambiguity is not just bad for computers, it's bad for humans too - misunderstanding requirements is a huge cause for delay, bugs and dissatisfaction of customers. The downside of writing for machines rather than humans though is that there is also no need for explanation of purpose or assumptions, which is the only thing I still add inline comments for. But even then, these can often be expressed in the language, and where possible they absolutely should be. If your code assumes some property or invariant, assert it! Or use the type system or tests to state and verify it. This way, the assumptions are constantly re-validated automatically by your build system, so the second they no longer hold you will know to reassess the code in question. I hate maintaining old code written in a convoluted way with a comment explaining that the purpose is to improve efficiency, and then realising that the code in question is no longer a bottleneck and the efficiency is irrelevant. If literate programming helps me understand the convoluted code, great, but what I really want is something that helps me validate that it even needs to be so convoluted in the first place, and lets me know the second I can simplify it again.