41 ms·
This is a really nice and illuminating post! Especially cool how all evaluation is done by line 33. (Minor comment: Line 14 may benefit from using a different
by svat 8y ago
This is a really nice and illuminating post!
Especially cool how all evaluation is done by line 33. (Minor comment: Line 14 may benefit from using a different variable for the function instead of “c”.)
An “aside” comment, as the title mentions “literate C++” [Edit: This was submitted as something like “Build me a Lisp: in less than 50 lines of literate C++”]. This post exemplifies one aspect of literate programming (as Knuth envisioned it), which is “let us concentrate rather on explaining to human beings what we want a computer to do.”
But there are two further features that Knuth-style LP systems have, which are missing here:
• The ability to write your program / explanation in any order (ideally, an order that is best for presentation, rather than an order demanded by the compiler). In this case, the program is explained strictly in the order of lines in the program, which imposes some awkwardness. (Not only in the explanation, but also in the code: e.g. putting a #include on line 34 of 49.)
• Named chunks. So instead of writing
int main() {
try {
in one code block, and having to continue it later, you could write something like, say,
int main() {
try {
[[say hello world]]
} [[handle errors]]
and later fill in the corresponding sections by name.
The original examples by Knuth are somewhat hard to read because they were written in Pascal and the programs were quite low-level but there's a great example available today (a book which won an Academy Award!), now free online — http://www.pbr-book.org/ http://www.pbr-book.org/ (random page: http://www.pbr-book.org/3ed-2018/Light_Transport_I_Surface_Reflection/Direct_Lighting.html http://www.pbr-book.org/3ed-2018/Light_Transport_I_Surface_R... )
But then again, the “no-tools” approach here does have the advantage of not requiring any special build step and not requiring the reader to understand any such conventions, so I guess that's a tradeoff. (They say one of the reasons literate programming never took off is that there are as many literate-programming tools as the number of people trying literate programming; everyone ends up having to write the tool that works for them.)
- DennisP 8y agoSo this (excellent) post would actually be semiliterate C++. The Babel tool in emacs org-mode looks like it does the real thing: https://orgmode.org/worg/org-contrib/babel/intro.html https://orgmode.org/worg/org-contrib/babel/intro.html
- saagarjha 8y agoHonestly, I found the code a bit hard to follow, mostly because everything was so disjoint. It would be nice to have "folding" so I could move comments out the way once I'm done with them, to allow me to look at the code as a whole. Once I know what a snippet does, I can "name" chunks myself mentally–any further labels, especially multi-lines ones that show up in between code, are unnecessary.
- KayEss 8y agoFollow the link to the Gist <https://gist.github.com/KayEss/45a2e88675832228f57e2d598afc02ae> https://gist.github.com/KayEss/45a2e88675832228f57e2d598afc0... and your code editor should give you the comment folding you want.
- saagarjha 8y agoFair point, although my editor (Sublime Text) is apparently to stupid to recognize those as block comments…
- svat 8y agoYour comment illustrates another reason literate programming never took off :-) Until a reader has spent enough time reading and getting familiar with the conventions, how to navigate, etc (in my case it was several dozen hours), they experience a lot of resistance against simply reading the literate program, and keep wanting to read “the real code”. Ultimately a program is a set of instructions to a computer, and when we as humans look at a program we're trying to conceptualize how these instructions are organized. (Essentially, “translate” them into a mental map.) We have so much more experience doing this with “real” code, knowing what we can ignore and when, and being able to do this at well — e.g. with things like function docstrings or public/private declarations, we're able to read them once and then have them basically fade away from our consciousness so we don't read them again. When faced with unfamiliar conventions, it takes a while to get that ability again.
- javajosh 8y agoPerhaps literate programs shine when they help us build that mental map. One way is positively describing parts of the map with metaphor or intent (where the OP shines). Another way is by discussing alternatives that weren't used. Yes, this can be a lot of content and sometimes crowds out the code, as in this example.