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.

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!

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

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.

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?

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

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.

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.

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.

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.

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

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.

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

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.

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.

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

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

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