from Hacker News

Literate CoffeeScript

by jedschmidt on 2/25/13, 8:33 AM with 108 comments

• by jashkenas on 2/25/13, 8:44 AM

  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.

  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

  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 10,000 bonus points if you port it over to Pygments and send a pull request to GitHub ;)

• by arocks on 2/25/13, 9:07 AM

  Should the order of documentation be same as order of code? For e.g. if I would like to start with explaining the main function at the bottom of the code, can this support that?

  If it does not it cannot be, strictly speaking, called Literate Programming: http://en.wikipedia.org/wiki/Literate_programming#Misconcept...

• by crazygringo on 2/25/13, 3:43 PM

  First, it looks great. It seems like such a trivial difference not to have #'s or /* / or whatnot... but somehow it does make all the difference. Almost like the code is meant to be read by people instead of computers (which is what the priority almost always should be).

  And second, the example [1] is a great model of good commenting practice -- explaining the why's, the workings, clarifying special cases. Especially with languages as concise and powerful as CoffeeScript, having as many lines of comments as lines of code, is a great balance.

  It seems like such a trivial idea, comments to the left, code indented, but it's one of the best ideas I've seen pop up in a long time -- especially because it heavily nudges you to treat comments as an integral part of the file, not just an extra, and to treat the file, from the beginning, as something for others to read. Bravo!

  [1] http://cl.ly/LxEu

• by anonymouz on 2/25/13, 9:04 AM

  http://en.wikipedia.org/wiki/Literate_programming for some background on literate programming. TeX is written in such a style.

• by gfodor on 2/25/13, 5:04 PM

  I'm interested to see where this goes, but one of the problems with literate programming is that it means that in addition to being a good programmer you also need to be a good writer. In other words, if you are a good programmer and a bad writer you are going to produce net bad work since your writing will confuse people who might otherwise have understood the code on its own, and if you are a good writer and a bad programmer there is a chance this will make it harder for others to realize your implementation sucks since it may be dressed in the most brillant, clear prose possible. (Of course one can make the argument that brilliant clear prose is a sign of brilliant clear thinking and hence code, but I am not so sure.) It also opens up the door for an entirely new dimension in code reviews. Imagine your resident grammar nazi jumping into code reviews now to perform edits to paragraphs upon paragraphs of comments. (This is probably the same person who agonizes over class names, so maybe you're already used to this :))

  I've found that there seems to be a decent correlation with writing skills and programming skills, but that's far from a fact and I've worked with people in every spot in the 2x2 skills matrix.

• by protez on 2/25/13, 11:18 AM

  Don't update now!

  I just updated it to checkout .litcoffee compilation and it worked out okay. But suddenly, all my express.js apps stopped working due to the exception from its connect module. I downgraded coffee to the previous version and all things turned fine again. It seems the package needs fixes. I like most parts of node except these surprising interconnections.

• by Tichy on 2/25/13, 9:00 AM

  "you can write it as a Markdown document — a document that also happens to be executable CoffeeScript code"

  Am I missing something or is that line literally the only explanation/documentation given as to what is literate CoffeeScript and how to use it? Must admit I have no idea how to use it now.

• by jahewson on 2/25/13, 11:20 AM

  Literate programming - why have terse comments when you can have a verbose and rambling narrative? I actually tried reading the TeX source code, and it was damn near impossible.

• by quii on 2/25/13, 9:53 AM

  It's a cool idea, but I am struggling to understand why this is better than say BDD; which not only effectively documents what your code does but also verifies it does what it says it should do.

• by agentultra on 2/25/13, 2:35 PM

  It just needs the ability to include source blocks in other source blocks and a way to tell the "compiler," how to organize the output files...

  For that I just use babel in org-mode... but you have to be an emacs person for that. I'm sure there are other literate systems (like the original: http://www-cs-faculty.stanford.edu/~uno/cweb.html)

• by franze on 2/25/13, 9:15 AM

  has anyone figured out what the syntax for

    You can now loop over an array backwards,
    without having to manually deal with the indexes.
  

  is?

• by arianvanp on 2/25/13, 11:44 AM

  I'm not sure if I agree with making comments a first-class citizen in a programming language.

  Good code documents itself and should be first-class. Comments should be there to clarify certain decisions that you've made while writing code.

  Handing out citizenship to the comments just clutters the code flow and will stimulate bad commenting behaviour.

  I really don't see any pros for 'executable' markdown at the moment, apart from being cool.

• by jimjeffers on 2/27/13, 12:18 AM

  Is anyone planning on some sort of support for .litcoffee in docco? It'd be awesome if docco could compile the markdown documents into HTML files and keep that swell dropdown navigation in the top right hand corner available. Generating docs as I was in my earlier projects seems to be the only gap. Otherwise I'm using litcoffee on a current client project and really loving it!

• by andyjohnson0 on 2/25/13, 12:24 PM

  I remember getting quite interested in literate programming back in the early nineties, but I've barely heard anything about it since then.

  Has anyone (apart from Knuth) used LP for any real work of significant size? What was the justification of doing the, presumably substantial, work to add literate programming to coffescript?

• by zbowling on 2/25/13, 8:41 AM

  I'm cofused by what "executable" means in this context with markdown. Is this some kind of documentation support for coffeescript?

  or is the code executable in the blocks in the markdown script and literate mode is a way to invoke "documentation" basically if the file is a .litcoffee document instead of a .coffee document?

• by pkorzeniewski on 2/25/13, 10:08 AM

  Very interesting idea, great for creating architecture outline, generating documentation and understanding code.

• by ww520 on 2/25/13, 8:40 AM

  Interesting development with the literate programming. Certainly a bold move. Kudos for trying some new!

• by arvidkahl on 2/25/13, 6:36 PM

  Could you please state the reasons for this change: 'cannot return a value from a constructor'. Besides breaking working code, this feels more like an added restriction than an added feature. I'd love to know why this is in 1.5. Thanks!

• by transfire on 3/3/13, 12:36 AM

  Ruby's had something like this for awhile --a test framework called [QED](http://rubyworks.github.com/qed). Made for testing, but technically it could be used for anything.

• by ms123 on 2/25/13, 2:17 PM

  I love that executable markdown style. I created a project some time ago that does just that. For the records, here it is: https://github.com/mikaa123/lilp

• by tbe on 2/25/13, 5:51 PM

  Cool idea to use Markdown's code snippet feature for literate programming :)

  I guess you could do this in any language by incorporating something like the following into your project's makefile:

    sed '/^\t/!d; s/^\t//'

• by vectorpush on 2/25/13, 7:19 PM

  This is cool. IMO, most comments are pretty superfluous, but I think this would be awesome for setting up visual groupings of related code sections.

• by nateabele on 2/25/13, 3:07 PM

  Oh.

  I was really hoping 'literate' meant you could read the code.

• by lastbookworm on 2/25/13, 10:33 PM

  I can see this being useful for writing tutorials or even a book. So many ideas for educational material swirling around in my head.

• by namuol on 2/25/13, 10:12 AM

  I'm not sure this is a good direction.

  We all want better documentation, but the problem with comments is that they can lie.

• by nathell on 2/25/13, 9:03 AM

  Which editor is this in the screenshot?

• by acedip on 2/25/13, 2:04 PM

  This is brilliant. love it.

• by coldtea on 2/25/13, 11:00 AM

  Shouldn't they be working on the goddamn Source Map support instead of literate gimmicks?

• by camus on 2/25/13, 11:26 AM

  So when does coffee-script becomes independent from javascript and gets its own CS->machine code compiler ?

• by wildchild on 2/25/13, 10:34 AM

  Cool, imperative code diluted with some poetry looks much better.

• by Mahn on 2/25/13, 11:23 AM

  This won't be a popular comment, but I have to admit I never really liked CoffeeScript. I've tried to like it, and it does seem more concise, but what's the point, it always seems clearer (to me) what something written in vanilla javascript is doing. I don't know, I guess I haven't done enough Python.