7 ms·

I'm pretty excited to see some of the first programs that folks might write with this -- I've got one of my own, a little 400 LOC (half of which is comments) st

I'm pretty excited to see some of the first programs that folks might write with this -- I've got one of my own, a little 400 LOC (half of which is comments) static blogging engine that's currently powering http://ashkenas.com http://ashkenas.com. Part of the idea is that, because first and foremost you're writing a document describing what you're doing, and then filling the the implementation in the gaps ... you end up structuring the program differently than if you started out with the code was at the top level, as usual. For me, it was a fun process -- start with an outline, expand that into paragraphs below, then indent four spaces and implement each paragraph... I'll share the full bit when I make it out of the woods next week, but for now, here's a sneak peek of a rough draft to give a flavor: http://cl.ly/N8Kx http://cl.ly/N8Kx Edit: If anyone wants a copy of the hybrid Markdown/CoffeeScript syntax highlighter (for TextMate or Sublime Text), it's available here in the "Syntaxes" folder. https://github.com/jashkenas/coffee-script-tmbundle https://github.com/jashkenas/coffee-script-tmbundle 10,000 bonus points if you port it over to Pygments and send a pull request to GitHub ;)

phpnode 14y ago
don't you find it a little painful to write code like that? When literate mode was first announced I had a go re-writing some small scripts in that style and for some reason I found it a bit of a chore, especially when commenting on just one or two lines. I've been using ### comment blocks ### instead and I find that more readable, especially when dealing with indented code, e.g. a class body. Edit - here's an example of some coffeescript written in this "illiterate" way, i'm using it with a (work in progress) preprocessor that spits out tests, html, markdown etc - https://gist.github.com/phpnode/2bf86b9633032a51d036 https://gist.github.com/phpnode/2bf86b9633032a51d036
- jashkenas 14y ago
  I think it definitely depends on what you're doing. We're by no means deprecating "ordinary" mode, where the code remains primary, and the comments are secondary. For me, it's most interesting for both exploratory programming -- where you don't quite know how to solve the puzzle yet, but you're in the process of figuring it out, and writing notes to yourself as you do so; as well as for polishing up finished pieces of code -- where you've carefully put a library together in a certain way, and you want to document every significant method with an explanation of why it's written the way it is.
epidemian 14y ago
Hey Jeremy, congratulations for the 1.5 release; really awesome stuff there! I'm especially liking the new REPL =D About Literate CoffeeScript, i wonder if it'd play nice with moderately complex pieces of code, which, in general, tends to be quite nested/indented. The example on the CoffeeScript compiler, scope.litcoffee[1], looks quite nice, but at the same time it's a fairly simple class; it doesn't need intra-method comments for example. For more complex pieces of code[2], that make use of comments in fairly indented sections to explain what's going on, do you think the literate style would work too? Or would then make more sense to mix both worlds and use hash-style (#) comments for the more nested bits and literate-style "comments" for describing the more top-level things? For reading code, i personally really really like the two-column Docco style[3]; the way the comments don't interrupt the code but are there on a side instead. The challenge would be how to see the source code in that nice two-column style while editing :D Edit: well, phpnode asked basically the same thing regarding indentation (should use F5 more often). [1]: https://github.com/jashkenas/coffee-script/blob/master/src/scope.litcoffee https://github.com/jashkenas/coffee-script/blob/master/src/s... [2]: like nodes.coffee: https://github.com/jashkenas/coffee-script/blob/master/src/nodes.coffee https://github.com/jashkenas/coffee-script/blob/master/src/n... [3]: nodes.coffee post Docco: http://coffeescript.org/documentation/docs/nodes.html http://coffeescript.org/documentation/docs/nodes.html
- jashkenas 14y ago
  1) Significant whitespace and Markdown-indented code blocks don't really play well together, as now you're operating relative from the indented block, instead of operating from the far left. Ultimately, I think it has a tendency to encourage you to keep things fairly flat, and broken up into smaller methods -- which isn't necessarily a bad thing. 2) I do think it works in heavily indented sections, though -- you just have a single line of prose set off to the left, instead of having a single line set off with a hash. 3) Yep -- I'm hoping to update Docco to parse these files as well, and after that, I'd love to have a nice PDF generator for these, with highlighting and hyperlinks. It's on the list.
philbo 14y ago
Beyond any educational benefit, what do you see as the advantages of programming in this way? I and most of the programmers I socialise with tend to see comments as a bad smell; they're fine every now and then but if there are more than a few of them, something is wrong. How do you prevent the comments from becoming lies? By which I mean, how can you ensure that people updates the comments in accordance with changes to the code that occur over time. Also what impact do you think this approach might have on the way people write the code itself; naming variables and arguments, decomposing functions into smaller units and so on?
- chakrit 14y ago
  On a project I am working on, I write all my public interfaces in literate programming style so it can doubles as comprehensive API documentation to put up on GitHub pages or websites or printed for sending to 3rd parties without me having to carefully correlate code and a separate document (they'are already there together.) On other, more private parts of the code, I just write it normally, with minimal comments. Another benefits is that, when you change the code, the relevant documentation is right there next to it. I find this minimizes the chance of having an outdated documentation and make it very simple and convenient to update the docs when I update any public interfaces.
- wereHamster 14y ago
  Comments should not describe what the code does. That should be obvious from the code itself. They should describe why the code does what it does. Hidden assumptions, dependencies or that sort of thing. Things that are not obvious from looking at one particular block of code. Often comments are transformed into API documentation (JavaDoc, rdoc, tomdoc, docco etc). The less you can put into the type system (or if you use a language with no type system at all), the more you have to explain in your comments.
  - account_taken 14y ago
    While the recommended practice is not to describe what the code does, I let go of that practice a while ago. Most of our projects are polyglot and our new hires don't know what a section does in an unfamiliar language. That takes time. The learning process is expedited by describing what the code does. Moreover, I tend to pseudocode the non-trivial sections in comments anyway. There's no need to throw that away.
lloeki 14y ago
While the code is "accessible" to the markdown side, I wish the inverse was true so that the text part would be reified and accessible from the JS/CS side, not merely ignored. Think Python's __doc__.
jostylr 14y ago
I have recently written a general literate programming environment that one can use to write just about anything: https://github.com/jostylr/literate-programming https://github.com/jostylr/literate-programming It also uses markdown and its code conventions. It is still early stages, but it seems to be working fine. It compiles itself, of course. It has the ability to compile snippets mid-compiling. So one probably could, for instance, write small self-contaied snippets of coffeescript and potentially merge the compiled version into a normal javascript script, all of which is being compiled from a single (or multiple if you like) markdown documents.
- samatman 14y ago
  This is a fantastic idea, reading the self-documenting code right now. This is like a cross between literate programming and a C preprocessor, with a sprinkle of build management. I can picture a few powerful ways of using this. Thanks for sharing!
bguthrie 14y ago
Congratulations on the release! Although I'm a great fan of Coffeescript, I am and remain a skeptic of the what I've seen of the literate-programming style. Well-written tests or specifications, with integrated documentation-generation tooling, provide many of the same code-structuring benefits without the disadvantage of additional code clutter, and with the advantage of enforceability. Documentation is not enforceable, and notoriously prone to decay. That being said, this is an interesting idea, and I'll certainly give it a go.
raganwald 14y ago
I'm extremely excited. Congratulations! first and foremost you're writing a document describing what you're doing, and then filling the the implementation in the gaps ... you end up structuring the program differently than if you started out with the code was at the top level, as usual. I had the exact same experience when I wrote a HashLife implementation in CoffeeScript using Docco: http://recursiveuniver.se http://recursiveuniver.se In my case, instead of working from an outline down to details, I worked with the idea of a simple implementation to which successive chapters added new functionality with aspect-oriented programming. A different narrative style led to a completely different architecture.
mintplant 14y ago
Is there a syntax highlighting plugin available for vim that currently supports this style?
- mintplant 14y ago
  For anyone who needs it, I've got a working implementation of this here: https://github.com/mintplant/vim-literate-coffeescript https://github.com/mintplant/vim-literate-coffeescript
opminion 14y ago
I have been using emacs org-mode to do something like this. It's great that it's now part of the language!
lallysingh 14y ago
Congrats, and kudos. Literate is a wonderful way to go for this. As a side note, any thought of adding iced-coffee's extensions? :-D

phpnode 14y ago

don't you find it a little painful to write code like that? When literate mode was first announced I had a go re-writing some small scripts in that style and for some reason I found it a bit of a chore, especially when commenting on just one or two lines. I've been using ### comment blocks ### instead and I find that more readable, especially when dealing with indented code, e.g. a class body. Edit - here's an example of some coffeescript written in this "illiterate" way, i'm using it with a (work in progress) preprocessor that spits out tests, html, markdown etc - https://gist.github.com/phpnode/2bf86b9633032a51d036 https://gist.github.com/phpnode/2bf86b9633032a51d036

jashkenas 14y ago
I think it definitely depends on what you're doing. We're by no means deprecating "ordinary" mode, where the code remains primary, and the comments are secondary. For me, it's most interesting for both exploratory programming -- where you don't quite know how to solve the puzzle yet, but you're in the process of figuring it out, and writing notes to yourself as you do so; as well as for polishing up finished pieces of code -- where you've carefully put a library together in a certain way, and you want to document every significant method with an explanation of why it's written the way it is.

epidemian 14y ago

Hey Jeremy, congratulations for the 1.5 release; really awesome stuff there! I'm especially liking the new REPL =D About Literate CoffeeScript, i wonder if it'd play nice with moderately complex pieces of code, which, in general, tends to be quite nested/indented. The example on the CoffeeScript compiler, scope.litcoffee[1], looks quite nice, but at the same time it's a fairly simple class; it doesn't need intra-method comments for example. For more complex pieces of code[2], that make use of comments in fairly indented sections to explain what's going on, do you think the literate style would work too? Or would then make more sense to mix both worlds and use hash-style (#) comments for the more nested bits and literate-style "comments" for describing the more top-level things? For reading code, i personally really really like the two-column Docco style[3]; the way the comments don't interrupt the code but are there on a side instead. The challenge would be how to see the source code in that nice two-column style while editing :D Edit: well, phpnode asked basically the same thing regarding indentation (should use F5 more often). [1]: https://github.com/jashkenas/coffee-script/blob/master/src/scope.litcoffee https://github.com/jashkenas/coffee-script/blob/master/src/s... [2]: like nodes.coffee: https://github.com/jashkenas/coffee-script/blob/master/src/nodes.coffee https://github.com/jashkenas/coffee-script/blob/master/src/n... [3]: nodes.coffee post Docco: http://coffeescript.org/documentation/docs/nodes.html http://coffeescript.org/documentation/docs/nodes.html

jashkenas 14y ago
1) Significant whitespace and Markdown-indented code blocks don't really play well together, as now you're operating relative from the indented block, instead of operating from the far left. Ultimately, I think it has a tendency to encourage you to keep things fairly flat, and broken up into smaller methods -- which isn't necessarily a bad thing. 2) I do think it works in heavily indented sections, though -- you just have a single line of prose set off to the left, instead of having a single line set off with a hash. 3) Yep -- I'm hoping to update Docco to parse these files as well, and after that, I'd love to have a nice PDF generator for these, with highlighting and hyperlinks. It's on the list.

philbo 14y ago

Beyond any educational benefit, what do you see as the advantages of programming in this way? I and most of the programmers I socialise with tend to see comments as a bad smell; they're fine every now and then but if there are more than a few of them, something is wrong. How do you prevent the comments from becoming lies? By which I mean, how can you ensure that people updates the comments in accordance with changes to the code that occur over time. Also what impact do you think this approach might have on the way people write the code itself; naming variables and arguments, decomposing functions into smaller units and so on?

chakrit 14y ago
On a project I am working on, I write all my public interfaces in literate programming style so it can doubles as comprehensive API documentation to put up on GitHub pages or websites or printed for sending to 3rd parties without me having to carefully correlate code and a separate document (they'are already there together.) On other, more private parts of the code, I just write it normally, with minimal comments. Another benefits is that, when you change the code, the relevant documentation is right there next to it. I find this minimizes the chance of having an outdated documentation and make it very simple and convenient to update the docs when I update any public interfaces.
wereHamster 14y ago
Comments should not describe what the code does. That should be obvious from the code itself. They should describe why the code does what it does. Hidden assumptions, dependencies or that sort of thing. Things that are not obvious from looking at one particular block of code. Often comments are transformed into API documentation (JavaDoc, rdoc, tomdoc, docco etc). The less you can put into the type system (or if you use a language with no type system at all), the more you have to explain in your comments.
- account_taken 14y ago
  While the recommended practice is not to describe what the code does, I let go of that practice a while ago. Most of our projects are polyglot and our new hires don't know what a section does in an unfamiliar language. That takes time. The learning process is expedited by describing what the code does. Moreover, I tend to pseudocode the non-trivial sections in comments anyway. There's no need to throw that away.

lloeki 14y ago

While the code is "accessible" to the markdown side, I wish the inverse was true so that the text part would be reified and accessible from the JS/CS side, not merely ignored. Think Python's __doc__.

jostylr 14y ago

I have recently written a general literate programming environment that one can use to write just about anything: https://github.com/jostylr/literate-programming https://github.com/jostylr/literate-programming It also uses markdown and its code conventions. It is still early stages, but it seems to be working fine. It compiles itself, of course. It has the ability to compile snippets mid-compiling. So one probably could, for instance, write small self-contaied snippets of coffeescript and potentially merge the compiled version into a normal javascript script, all of which is being compiled from a single (or multiple if you like) markdown documents.

samatman 14y ago
This is a fantastic idea, reading the self-documenting code right now. This is like a cross between literate programming and a C preprocessor, with a sprinkle of build management. I can picture a few powerful ways of using this. Thanks for sharing!

bguthrie 14y ago

Congratulations on the release! Although I'm a great fan of Coffeescript, I am and remain a skeptic of the what I've seen of the literate-programming style. Well-written tests or specifications, with integrated documentation-generation tooling, provide many of the same code-structuring benefits without the disadvantage of additional code clutter, and with the advantage of enforceability. Documentation is not enforceable, and notoriously prone to decay. That being said, this is an interesting idea, and I'll certainly give it a go.

raganwald 14y ago

I'm extremely excited. Congratulations! first and foremost you're writing a document describing what you're doing, and then filling the the implementation in the gaps ... you end up structuring the program differently than if you started out with the code was at the top level, as usual. I had the exact same experience when I wrote a HashLife implementation in CoffeeScript using Docco: http://recursiveuniver.se http://recursiveuniver.se In my case, instead of working from an outline down to details, I worked with the idea of a simple implementation to which successive chapters added new functionality with aspect-oriented programming. A different narrative style led to a completely different architecture.

mintplant 14y ago

Is there a syntax highlighting plugin available for vim that currently supports this style?

mintplant 14y ago
For anyone who needs it, I've got a working implementation of this here: https://github.com/mintplant/vim-literate-coffeescript https://github.com/mintplant/vim-literate-coffeescript

opminion 14y ago

I have been using emacs org-mode to do something like this. It's great that it's now part of the language!

lallysingh 14y ago

Congrats, and kudos. Literate is a wonderful way to go for this. As a side note, any thought of adding iced-coffee's extensions? :-D