9 ms·
Literate CoffeeScript
- transfire 14y agoRuby's had something like this for awhile --a test framework called [QED](http://rubyworks.github.com/qed http://rubyworks.github.com/qed). Made for testing, but technically it could be used for anything.
- ww520 14y agoInteresting development with the literate programming. Certainly a bold move. Kudos for trying some new!
- zbowling 14y agoI'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?
- ww520 14y agoOne source file, two compiled outputs: Markdown for documentation or javascript for execution.
- jashkenas 14y agoIf 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.
- mikeknoop 14y agoAfter reading the docs and comments, this was the comment/explanation that made the light-bulb click.
- chc 14y agoIt 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.
- jashkenas 14y agoI'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 agodon'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 agoI 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.
- Tichy 14y ago"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.
- talklittle 14y agoThe next sentence includes links to bits of the compiler in literate CoffeeScript. https://gist.github.com/jashkenas/3fc3c1a8b1009c00d9df 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.
- mosselman 14y agoThanks for explaining.
- jashkenas 14y agoI'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.
- Tichy 14y agoThanks!
- melvinmt 14y agoI 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?
- nathell 14y agoWhich editor is this in the screenshot?
- anonymouz 14y agohttp://en.wikipedia.org/wiki/Literate_programming http://en.wikipedia.org/wiki/Literate_programming for some background on literate programming. TeX is written in such a style.
- arocks 14y agoShould 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#Misconceptions http://en.wikipedia.org/wiki/Literate_programming#Misconcept...
- jashkenas 14y agoAh, 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
- mhd 14y agoWell, 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.
- vog 14y agoThat 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/ http://www.profv.de/literate-programming/
- franze 14y agohas anyone figured out what the syntax for You can now loop over an array backwards, without having to manually deal with the indexes. is?
- quii 14y agoIt'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.
- chrisdevereux 14y agoThat 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.
- phpnode 14y agoi'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.
- tomjen3 14y agoBecause 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.
- deleted 14y ago[deleted]
- pkorzeniewski 14y agoVery interesting idea, great for creating architecture outline, generating documentation and understanding code.
- namuol 14y agoI'm not sure this is a good direction. We all want better documentation, but the problem with comments is that they can lie.
- libria 14y agoCommenting 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.
- namuol 14y agoI 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.
- lallysingh 14y agoCode review -- look for an equal diff in the docs with the source. No code review? Bigger problems.
- wildchild 14y agoCool, imperative code diluted with some poetry looks much better.
- coldtea 14y agoShouldn't they be working on the goddamn Source Map support instead of literate gimmicks?
- venus 14y agoOh 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!
- camus 14y agoI believe the guy working on source-maps has been kick-started
- jashkenas 14y agoA bit of that is in this release as well, thanks to Jason Walton. https://github.com/jashkenas/coffee-script/blob/master/src/grammar.coffee#L43-L56 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 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.
- coldtea 14y agoThanks 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).
- protez 14y agoDon'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.
- jashkenas 14y agoWhat exactly was the error?
- protez 14y agoIt 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.
- nadaviv 14y agoTry diffing the compiled source for 1.4 and 1.5.
- kcbanner 14y agorofl
- jahewson 14y agoLiterate 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.
- ajross 14y agoI 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...
- Mahn 14y agoThis 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.
- mratzloff 14y agoIt won't be a popular comment because it's not germane to the conversation at hand.
- Mahn 14y agoWe 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.
- Cushman 14y agoThis 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.
- camus 14y agoSo when does coffee-script becomes independent from javascript and gets its own CS->machine code compiler ?
- NoahTheDuke 14y agoI would guess when Javascript dies. So, never.
- tomjen3 14y agoIt 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.
- arianvanp 14y agoI'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.
- andyjohnson0 14y agoI 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?
- acedip 14y agoThis is brilliant. love it.
- ms123 14y agoI 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 https://github.com/mikaa123/lilp
- agentultra 14y agoIt 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 http://www-cs-faculty.stanford.edu/~uno/cweb.html)
- nateabele 14y agoOh. I was really hoping 'literate' meant you could read the code.
- crazygringo 14y agoFirst, 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://cl.ly/LxEu
- gfodor 14y agoI'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.
- jashkenas 14y ago> 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.
- crazygringo 14y ago> 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.
- tbe 14y agoCool 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//'
- arvidkahl 14y agoCould 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!
- jashkenas 14y agoIt 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()
- vectorpush 14y agoThis is cool. IMO, most comments are pretty superfluous, but I think this would be awesome for setting up visual groupings of related code sections.
- lastbookworm 14y agoI can see this being useful for writing tutorials or even a book. So many ideas for educational material swirling around in my head.
- jimjeffers 14y agoIs 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!