4 ms·

I'm waiting eagerly for the Literate CoffeeScript support to land. My main concern with it is that it forces you to write the document in the same order you wa

by bergie 14y ago

I'm waiting eagerly for the Literate CoffeeScript support to land. My main concern with it is that it forces you to write the document in the same order you want the code to be extracted, which may not be the best order for explaining things. That is why classic Literate Programming tools like noweb[1] allow you to name the chunks of code and then arrange them into the generated files as you wish. You can see an example of this in action when I'm assembling noweb.php[2]. Also, agreed on the point that not every piece of example code is suitable for running as a test, so you'd optimally want some sort of annotation for that. Github-flavored Markdown[3] has the code block fencing syntax that would allow metadata like this. Something like: ```coffeescript # Just a regular, non-testable example ``` ```coffeescript;test # Example that is also a test ``` Actually, this same approach could be used for working with named chunks like noweb does. 1: http://en.wikipedia.org/wiki/Noweb http://en.wikipedia.org/wiki/Noweb 2: https://github.com/bergie/noweb.php/blob/master/README.txt#L324 https://github.com/bergie/noweb.php/blob/master/README.txt#L... 3: http://github.github.com/github-flavored-markdown/ http://github.github.com/github-flavored-markdown/

jashkenas 14y ago
> My main concern with it is that it forces you to write the document > in the same order you want the code to be extracted, which may not > be the best order for explaining things. ... Yep -- this is probably the main complaint raised when talking about tools like Docco or Markdown-as-source-code as "literate programming". But, it's a concern that I believe is entirely outdated. Modern dynamic languages make it easy to sequence your code as you like. The methods in a class may be listed in any logical order, helper functions can be listed in an appendix after the functions that make use of them, and so on. I find it hard to imagine an example where changing the order of the codebase would make the prose version more readable -- and wouldn't also make the code version more readable as well. I think that, unfortunately, the tangle/weave paradigm is a large part of why literate programming is barely used -- it introduces an entire level of build-time complexity that doesn't have any direct effect or benefit on your code. Here's hoping that the simplicity of having a file that is at once both executable code and publishable markdown is something that feels more usable to more programmers.

by bergie 14y ago

jashkenas 14y ago

> My main concern with it is that it forces you to write the document > in the same order you want the code to be extracted, which may not > be the best order for explaining things. ... Yep -- this is probably the main complaint raised when talking about tools like Docco or Markdown-as-source-code as "literate programming". But, it's a concern that I believe is entirely outdated. Modern dynamic languages make it easy to sequence your code as you like. The methods in a class may be listed in any logical order, helper functions can be listed in an appendix after the functions that make use of them, and so on. I find it hard to imagine an example where changing the order of the codebase would make the prose version more readable -- and wouldn't also make the code version more readable as well. I think that, unfortunately, the tangle/weave paradigm is a large part of why literate programming is barely used -- it introduces an entire level of build-time complexity that doesn't have any direct effect or benefit on your code. Here's hoping that the simplicity of having a file that is at once both executable code and publishable markdown is something that feels more usable to more programmers.