4 ms·

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 i

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.

e12e 11y ago
IMHO the examples you cite, such as the underscore-example has very little to do with any meaningful definition of "Literate Programming". While modern languages like JavaScript (or lisp ;-) allow for a very free structure, and ordering of the code in accordance with how comments might fit, or the thought process that went into the design -- that's just proper programming style: proper comments, sane structure. And I'm not convinced it does much to make sure the narrative keeps up with the code, as the code changes. The meta-programming that (no)web enables for C/Pascal can be very helpful, as one might have code structured around loops (an algorithm that deals with an iterator, i, and an Array, a) -- code that might see re-use in places where the functionality doesn't lend itself (in a C/Pascal) to re-use in a function/procedure/module. But as in-lining has become more and more main stream, and micro-optimizations have become less and less needed -- this kind of meta-programming -- introduction of named code blocks to languages that otherwise don't have them -- has become less interesting. I think a better example of "evolved" or "modern" LP is python doctests[1]. It's just a small example, but it is a way to tie commentary tightly with function, and allows for "Here's what this code does"-comment -- that can actually be used for testing. But even doctests are a pale shadow of what LP offers. On the other hand -- some of the benefits in terms of structure/folding is also provided by powerful editors/IDEs. I still think LP can have it's place, especially when writing code meant to be read as a teaching tool, like: http://en.literateprograms.org/Binary_search_(Java) http://en.literateprograms.org/Binary_search_(Java) LP often lends itself well to a top-down structure, regardless of any limitations in the underlying programming language (or common concessions to efficiency, manual in-lining etc). To a certain extent, one could/can/sometimes-should write C programs like: include1 include2 action_function setup_helper sub_step1 sub_step2 setup_helper sub_step1 sub_step2 main handle_args action_function handle_args But frequently it doesn't make sense to keep the actual sources quite like that -- if nothing else because there might be platform ifdefs, various libraries in use etc. [1] https://docs.python.org/2/library/doctest.html https://docs.python.org/2/library/doctest.html

e12e 11y ago

IMHO the examples you cite, such as the underscore-example has very little to do with any meaningful definition of "Literate Programming". While modern languages like JavaScript (or lisp ;-) allow for a very free structure, and ordering of the code in accordance with how comments might fit, or the thought process that went into the design -- that's just proper programming style: proper comments, sane structure. And I'm not convinced it does much to make sure the narrative keeps up with the code, as the code changes. The meta-programming that (no)web enables for C/Pascal can be very helpful, as one might have code structured around loops (an algorithm that deals with an iterator, i, and an Array, a) -- code that might see re-use in places where the functionality doesn't lend itself (in a C/Pascal) to re-use in a function/procedure/module. But as in-lining has become more and more main stream, and micro-optimizations have become less and less needed -- this kind of meta-programming -- introduction of named code blocks to languages that otherwise don't have them -- has become less interesting. I think a better example of "evolved" or "modern" LP is python doctests[1]. It's just a small example, but it is a way to tie commentary tightly with function, and allows for "Here's what this code does"-comment -- that can actually be used for testing. But even doctests are a pale shadow of what LP offers. On the other hand -- some of the benefits in terms of structure/folding is also provided by powerful editors/IDEs. I still think LP can have it's place, especially when writing code meant to be read as a teaching tool, like: http://en.literateprograms.org/Binary_search_(Java) http://en.literateprograms.org/Binary_search_(Java) LP often lends itself well to a top-down structure, regardless of any limitations in the underlying programming language (or common concessions to efficiency, manual in-lining etc). To a certain extent, one could/can/sometimes-should write C programs like: include1 include2 action_function setup_helper sub_step1 sub_step2 setup_helper sub_step1 sub_step2 main handle_args action_function handle_args But frequently it doesn't make sense to keep the actual sources quite like that -- if nothing else because there might be platform ifdefs, various libraries in use etc. [1] https://docs.python.org/2/library/doctest.html https://docs.python.org/2/library/doctest.html