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 ;)
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
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.
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.
I can picture a few powerful ways of using this. Thanks for sharing!
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:
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.
###
comment blocks
###
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
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.
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?
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.
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.
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.
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.
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!
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?
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.
As a side note, any thought of adding iced-coffee's extensions? :-D
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.
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).
If it does not it cannot be, strictly speaking, called Literate Programming: http://en.wikipedia.org/wiki/Literate_programming#Misconcept...
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 programOut-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'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/
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!
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"
}
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
}
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.
y = m*x + b
where
m = calculateSlope()
b = getYIntercept()
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.
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.
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.
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?
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.
coffee yourprogram.litcoffee
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.
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
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.
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.
Like the comments newbies sometimes make in code
//Assign 0 to i
i = 0;
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.
###
@it should return true
expect(foo()).to.be.true
###
foo = -> true
We all want better documentation, but the problem with comments is that they can lie.
Are you positing that better formatting encourages worse comments/documentation? I'm of the opinion that their presentation is independent of their quality.
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.
No code review? Bigger problems.
You can now loop over an array backwards,
without having to manually deal with the indexes.
Edit: Link to Soda theme on Github: https://github.com/buymeasoda/soda-theme
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...
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
widget = Widget.lookup()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!
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)
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.
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 guess you could do this in any language by incorporating something like the following into your project's makefile:
sed '/^\t/!d; s/^\t//'I was really hoping 'literate' meant you could read the code.