Literate CoffeeScript | Hacker News Reader

Literate CoffeeScript

coffeescript.org

234 pointsjedschmidt108 comments

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 ;)

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

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.

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/s...

[2]: like nodes.coffee: https://github.com/jashkenas/coffee-script/blob/master/src/n...

[3]: nodes.coffee post Docco: http://coffeescript.org/documentation/docs/nodes.html

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.

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?

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.

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.

Comments also function as a SUMMARY of what the code does.

A file should always have a summary at the top. A function more than a couple lines long should always have a summary explaining what it does.

In the real world, people don't have time to read your 5,000 lines of code -- they need to be able to jump in, make a change, and not break things. Comments are very important for this.

"comments as a bad smell"

I don't understand this. You get two orthogonal things, code quality and comments quality, and you tie them together for some reason - but they are still orthogonal.

Good code that is well documented is always a much better thing than a good code that is not documented (with comments). And bad code with good comments is still much better than bad code without comments at all.

On the other hand bad comments are just bad.

I can't help but think that people who consider comments a "smell" do so because they can't write good comments. Well, writing good comments is hard, but that doesn't mean we shouldn't try.

Well part of the idea is that if you have to write so many comments, your code might be unnecessarily complex or hard to understand. Often, straightforward code is better than clever code.

Also, having paragraphs of comments is often distracting and makes it really difficult to skim through files to find things. To me it seems a little excessive to have two paragraphs of comments for a 5 line method without a good reason.

I know that you often need to do that for RDoc or YARD or other documentation generators, and documenting mature code can be good, but it might be a little overkill for experimenting around.

That being said, there's absolutely nothing wrong with having the ability to do it and make it look pretty if you want to.

In other news: Emacs is better than Vim and static typing is better than dynamic typing.

What I'm trying to say is that discussion about comments in code is useless unless it's based on real code - and then it's still largely a matter of one's habits and expectations. In case of your post here, for example, I can already see that we are talking about different things and that we have very different ways of working with code. To convince you that good comments are good I'd have to first explain to you how I work with code already written, then how I write code, then how I write comments and then define what a "good" comment is. I'm positive that I would succeed, however I have no time now to attempt this and you're probably not that interested either.

Anyway, I'm much more productive when working with heavily commented (with good comments) code. I don't like the loss of productivity I see when working with code without comments. It's entirely possible that you're working in a way that doesn't benefit from comments, and it's nothing bad in itself, but you shouldn't use this as an argument against comments in code.

    > Beyond any educational benefit, what do you see as the 
    > advantages of programming in this way?

For me (and I'm just getting started here, I've only been playing around with this in earnest in the context of the little blog engine, and there are certainly many different ways of going about it), it makes the process of exploratory coding feel very different. Instead of thinking up a series of classes or functions that might solve the problem, and starting to write them -- I instead start by outlining (literally) what I want the program to do, and then describe the functionality in paragraphs, and then implement those paragraphs.

When the paragraphs have code below them that does what they say they do, the thing works. When I end up coding myself into a corner, I rewrite the paragraph and change the code. It's really a very different process than usual. It's also definitely more work than just doing code and omitting comments -- it takes a bit of elbow grease to prevent the comments from becoming lies ... but it's the same type of work as preventing bits of your codebase from becoming dead code.

For me, it seems to make me organize code into smaller functions grouped together into sections, use less classes, and care more about putting things in the place where you're talking about them, and less about putting similar things together in one block of code. For example, I started to require things close to the paragraph where I first mention them, instead of putting all requires at the top of the file. At least, that's how it feels so far.

Quite interesting, I do something similar to that on a smaller scale. When I do a class/method, I usually just put comments describing what's going to happen and that makes me thing of cases I might have missed otherwise and then I add the code below each comment.

Will try literate coffeescript next time I use it.

I'm glad to know I'm not the only person who works this way. My source files often have a paragraph or two at the top that explains my intentions for that class/module as well as explains the usage of my domain language. I never see this in other people's code though.

I agree with people who say that the code itself should read very clearly, but the fact is that even when writing an article or paper you have to disambiguate your own writing, clarify your usage of terms and present some context up front. Otherwise people can take away a very mistaken impression of your text, and it is certainly no less true for code.

Comments give you a way to describe your analysis of the problem. They also give you a way to describe how the code solves the problem.

If the code doesn't need any human problem analysis, perhaps it's redundant? Could a higher-level analysis have solved the entire class of problems?

    Beyond any educational benefit, what do you see as the advantages of programming 
    in this way?

For me, literate programming has been exceptional for organizing my thoughts, and preventing me from thinking myself in loops, or hitting a wall of decision paralysis. Being able to express what I'm trying to do in English, Spanish, Mandarin, etc., is a prerequisite to being able to express it in Ruby, Python, or CoffeeScript.

"..most of the programmers I socialise with tend to see comments as a bad smell.."

I think it really depends on the language and context. Most of my development these days is native iOS on the client side, and Node.js via CoffeeScript on the server. The more verbose a language or API is, the more self-documenting it is. On the other hand, the more concise a language is, the more documentation it requires. I find that I need very little documentation to write maintainable Cocoa code. CoffeeScript is different story though. I can come back to 3-4 month old CoffeeScript code and have difficulty remembering what it did. It needs more documentation to have the same readability as my Cocoa code. Not just the why, but also the how. Literal CoffeeScript seems to be a great solution to this problem. I can't wait to use it. Thanks jashkenas!

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.

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__.

I have recently written a general literate programming environment that one can use to write just about anything: 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.

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!

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.

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

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.

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

For anyone who needs it, I've got a working implementation of this here:

https://github.com/mintplant/vim-literate-coffeescript

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

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

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...

Ah, that old canard ;)

Modern programming languages (and JavaScript especially so) support defining your functions, creating your classes, and wiring things together, in any order you see fit. These days, TANGLE'ing and WEAVE'ing together a source file into a new line ordering, just to make a compiler happy, is unnecessary, and more trouble than it's worth. Just do:

    ... bulk of the file goes here ...

        main = ->
          run program

Well, there's more than one way to write literature, and there's more than one way to approach literate programs. So while I agree that you can do most of what you want with a more simplified approach, I don't think that Knuth's approach was just there to escape from Pascal's declaration syntax.

Out-of-order code can be quite useful if the literate document is the narrative of the code, how you derive your algorithms and create your functions. The final untangled code is devoid of this, and presents a more conventional structure. One example would be some global variables (or configuration hash, if that statement made you faint a bit). In the end, you probably would want at least one view of the code where this is collected in one spot, even if the programming language would theoretically allow you to declare it bit by bit all over the place.

On the other hand, this style doesn't lend itself that well to a constantly revised code base, as that would mean reading a narrative all over again.

That was exactly my line of thinking, too: Imaging you have written you literate program using all those literate-macros and TANGLE and WEAVE. If you're using a sufficiently powerful language, you can replace all your literate-macros with native language constructs.

That's why I never really felt the urge for those lterate-macros.

Moreover, I'm usually going into the opposite direction, writing LP programs that depend on as few tools as possible. For example, I wrote a LaTeX file that is also a valid shell script, executing the build instructions section when called from shell.

I named this experiment "Self-contained Literate Programming": http://www.profv.de/literate-programming/

Honestly, I am happy that you took a more pragmatic view of this. Whenever I try to write in literate style it never seemed as good as a naturally written documentation; never as good as Django documentation, for instance. I used to think it is because of my inability to structure my prose in a different order to my code.

Of course, most languages these days are late binding and do not enforce a strict ordering of parts of code. But I still think literate style is best suited for single-file source code documentation.

I truly look forward to reading your blogging engine created in literate style. All the very best!

By having the code in a differently ordered way, one can look at the compiled version to see how it flows; we get two views of the code instead of just one.

For example, we could use literate program flow to sketch the flow:

    if ( i<0 ) {
      "strip sign and reciprocate"
    }  else {
      "shift to make room for negatives"
    }

With function ordering, it would look similar but with dealWithNegative() kind of stuff and some sort of return value/scoping issue to think about. And that is all one gets.

But with literate program, you can actually look at the compiled code and get a different view; very helpful with scoping issues.

    if ( i<0 ) {
      i = 1/math.abs(i);
    }  else {
      i = i+1
    }

Admittedly, the compiled view should not be needed too often, but it is useful on occasion.

One also has the ability to quickly strip out long sections into their own snippets without having to worry about scope/closures/pass-in/return values/where to put the function.

You still need to declare variables before using them in an expression, though. I wish more languages would adopt the "where" syntax that Haskell and Miranda have. It lets you do things like:

  y = m*x + b
      where
      m = calculateSlope()
      b = getYIntercept()

I think this fits the literate programming style well.

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

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

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.

    > This is probably the same person who agonizes over 
    > class names, so maybe you're already used to this

Bingo. I think that for programming languages where clarity is already a common virtue (think, Ruby, Python, Clojure) -- folks already need to be writing clearly when they program: making the code clear to read, naming variables and functions very well, doing logical ordering of sections of code etc. That's already about halfway towards what you would do if you were accompanying the code with a bit of essay. I think the two worlds aren't as far apart as one might think.

> 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

To be a good team programmer, you already need to be a good communicator, and being a good writer is part of that.

In my opinion, it's one of the biggest things that separate programmers who only work well on their own, and programmers who work well as part of a team project.

It's not about grammar, it's just about clarity and explaining things well. But it's also not something you're born with, it's something anyone can learn, if they want to.

I disagree. No one's asking for a literary masterpiece, just a simple and organized explanation of what we're looking at. I would argue that the value is more in the process of creating this simple explanation, because it forces you to empathetically examine the code from a a foreign mindset, and from there to re-order and organize the code in a way that's amenable to conversational (simple) explanation.

This explanation may include requirements and other concerns, description of alternatives and why they were rejected, references to other parts of the codebase, and its high-level design intention (i.e. vision) in order to guide the direction of refactorings and extensions.

None of this requires analogy, symbolism, foreshadowing, subtlety of tone, or even a mastery of diction and syntax. Anything resembling Yeats or Dostoyevsky is counter-productive.

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.

What exactly was the error?

It said something about an indexOf method called from null object. I couldn't comprehend why coffee-script has anything to do with connect module, so just gave up at that point.

Try diffing the compiled source for 1.4 and 1.5.

rofl

"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.

The next sentence includes links to bits of the compiler in literate CoffeeScript. https://gist.github.com/jashkenas/3fc3c1a8b1009c00d9df

It's writing a Markdown document, where the code blocks, indented 4 spaces, are executed. And the rest of the document is essentially nicely-formatted comments in the form of Markdown.

Thanks for explaining.

I've added a bit more clarification to that paragraph. Hopefully soon we'll get proper highlighting for it committed into GitHub, and then a simple link should make things dead obvious.

Thanks!

I assume you place the .litcoffee files next to the .coffee files and only the indented parts in the .litcoffee files will be compiled to JS?

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.

I mostly agree. For 95% of code, it's simply a waste of time to try to "document" it like this. For the handful of situations where elaborate documentation wants to be stored with code (which basically means "automatic reference doc generation from API definitions") we have tools like Doxygen already that work well.

But there does remain that tiny subset of code that is so complicated that it can only be explained in prose. This includes things like, say, DCT implementations, tight SIMD assembly, complicated threadsafety architectures, oddball parser context dependency rules, etc... I can see wanting to read this stuff in a "literate" environment.

But... is anything you might use Coffeescript for going to contain code like that? I can't think of any good candidates offhand, beyond (perhaps) the coffeescript compiler itself...

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.

That was my though too. Are there any languages that let you write specs inline with the functions/classes that they test? That would be cool.

Edit: Having thought about it for a second, this could easily be done in most languages (with some preprocessing to strip out for deployment. Super easy in C-based languages). Not a convention I see anyone follow, though.

i'm working on a project that does this with doc comments. Basically you add a doc block like this:

    ###
    @it should return true
      expect(foo()).to.be.true
    ###
    foo = -> true

and the preprocessor extracts the test from the comment and associates it with the foo declaration.

Because BDD is too limited. It allows you only to state what should happen, not how or why.

Like the comments newbies sometimes make in code

    //Assign 0 to i
    i = 0;

Whereas with literate programming you can explain why you went with a particular style of code, why you went with a particular datastructure, etc. You can build up a narrative of code that will help the next programmer who comes along.

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)

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?

Sorry, I should add that to the changelog. It's just like looping over a range downwards (or by arbitrary increments).

    for item in list by -1

Very nice! I've wanted this for a long time.

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.

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!

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?

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?

One source file, two compiled outputs: Markdown for documentation or javascript for execution.

If the file extension is ".litcoffee", it means that you're writing a Markdown document, where the embedded bits of indented code are the executable part of the program.

Basically, it just inverts the usual power relationship in a piece of source code, where the code is primary and aligned along the left edge, and the comments are set off in little fenced blocks. Now the comments are primary, and the code is indented in little blocks -- but it's still the same executable piece of source code.

The neat bit is when you have it all working properly in a text editor, your prose being highlighted as Markdown, and your code being highlighted as CoffeeScript.

After reading the docs and comments, this was the comment/explanation that made the light-bulb click.

It means that you can run

  coffee yourprogram.litcoffee

and it will run the CoffeeScript program in your document.

On the other hand, you can run the file through your favorite Markdown viewer/processor and you'll see a nicely formatted version of the whole file with comments included.

In other words, it is both valid (Literate) CoffeeScript and valid Markdown.

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

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

I had to hand all my functional programming homework in in literate style in 1992 so 'New' is relative :-)

New to web development

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!

It is a restriction, and I'm a bit torn about it.

Apart from fixing bugs where you'd use a CoffeeScript `class` to extend from a native object, returning "other" values from a constructor is a bad idea because it makes your code lie.

    widget = new Widget

In CoffeeScript 1.5+, unless you go to great lengths to get around it, that's always going to return a new Widget -- in JavaScript, that could return a Dongle, an old and already used Widget, or anything else (that's not a primitive). If you want a function that maybe returns a new Widget, and maybe an old one, just use a normal function, not a constructor:

    widget = Widget.lookup()

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.

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

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//'

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.

Oh.

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

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

I'm not sure this is a good direction.

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

Commenting is still not required, AFAICT.

Are you positing that better formatting encourages worse comments/documentation? I'm of the opinion that their presentation is independent of their quality.

I fear that emphasis of documentation, to this extent, encourages us to read comments first and foremost, rather than the code.

I realize that the emphasis could be perceived the other way around (on the code, rather than the comments), but the author's intention seems to be the other way around.

Code review -- look for an equal diff in the docs with the source.

No code review? Bigger problems.

Which editor is this in the screenshot?

Sublime Text 2 with the Soda dark theme.

Edit: Link to Soda theme on Github: https://github.com/buymeasoda/soda-theme

Do you also happen to know which colour scheme that is?

Brilliance Black (42), a Halloween edition from several years back.

Thanks.

I can't seem to be able to find a version that looks like the screenshot though. Maybe you have a link? That would be great!

This is brilliant. love it.

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

Oh tell me about it! These good for nothing, lazy open source developers! How dare they spend their free time relaxing, or maybe working on something they're interested in, when they should be working on MY pet feature! They're just so INCONSIDERATE!

I believe the guy working on source-maps has been kick-started

A bit of that is in this release as well, thanks to Jason Walton. https://github.com/jashkenas/coffee-script/blob/master/src/g...

Source location information is now preserved through the parse, although it's not yet being emitted as a source map just yet. If you want to use CoffeeScript source maps today, feel free to use the Redux compiler, which does them just fine. Michael also has some other tools to make source maps even more convenient: https://github.com/michaelficarra/commonjs-everywhere

That said, I don't personally care for source maps all that much, placing a higher priority on generating readable and straightforward JavaScript output. Things like Literate CoffeeScript rank higher on the priority list.

Thanks for the response (well, given my tone).

But I think this literate thing never caught on for a reason. And I'd say the reason is marginal returns (over comments and clean code) and too much fuss.

As for the "entitlement", it's because people have been saying source maps would came to CS for 2 years now, and I've seen nothing related yet (even the crowd-funded project is not there).

Initially, I thought Source Maps would be kind of a big deal for CoffeeScript. After spending enough time with CS, I don't think I'd miss that feature. CS generates straight-forward JavaScript, you can't get confused with it.

sure, I sometimes forget when I'm reading JS in the debugger that I wrote it in CS. But I wouldn't discount the value of source mapping. I particularly find myself wanting it on the server, where I'm more likely to be depending on some one else's CS code, maybe in a deeply nested module somewhere. I'd really like accurate line numbers in server logs. So, sourcemaps are important - but so is super :{(}

Conveniently, CoffeScript is open source, so you can contribute as much or as little as you like. If your pet feature isn't progressing fast enough it's because you're not working fast enough on it.

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

I would guess when Javascript dies. So, never.

It doesn't have to become independent for that and I would imagine it never gets its own compiler (though it might get a plugin to GCC/Clang) because really, when you can make any choice of language, why chose CS? It is a better Javascript, but that isn't a very hard bar to cross.

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

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.

It won't be a popular comment because it's not germane to the conversation at hand.

We have all sorts of discussions here on HN that derail a bit from the topic of the main article linked, e.g. discussing smart TVs in a thread about webOS; I don't see how this is negative as long as there is still connection.

This isn't negative so much as irrelevant; CoffeeScript has been around long enough that we've had most of the discussion around what people like and don't like about it. If you don't like it, that's fine, but there's not a lot to talk about.

Reply on news.ycombinator.com