Jeremy, your code's comments are all hard-wrapped at column 80, but the code itself extends beyond that.
Do you tell your editor to hard-wrap each "block" of comments as you write (or edit) them, or is your editor configured to automatically hard-wrap all comments?
Either way, have you considered configuring your editor to soft-wrap comments while leaving your code alone? I'd say that's the most natural approach from a writing standpoint.
P.S. Every day, I use tools you've made. Keep making!
Yeah, in an ideal world, that would be better -- and I've tried writing like that ... but sooner or later I end up wanting to open the file in a location where the wrapping isn't configured properly, and all of the super long lines look terrible.
So I just tend to hard-wrap manually, out of habit, even when writing in a .txt file or an email. In fact, it's hard to stop myself from doing it in this textarea ;)
What editor do you use? With vim I think I've always been able to select comments and "gq" them to autoformat them to whatever the linewidth is set to.
I've always been excited by the idea of literate programming, and after having flirted with most of the other Javascript meta-languages, now use Coffeescript as my main language for both server-side (node.js) and client-side code. Is there currently a good syntax highlighting mode that properly displays .litcoffee files? I currently use Emacs with the coffee-mode major mode, but I don't think it's been updated yet.
I'm not aware of an Emacs one being updated yet, although I think that someone's finished it for Vim.
If you want to be an open-source hero -- go ahead and do it yourself ;) It's mainly a matter of taking the Markdown package, and the CoffeeScript package, and pasting the latter into the former, right where the syntax rule for "code block" goes.
I am a big fan of the goals of your work (CoffeeScript, Literate Programming).
Both projects make code easier to understand and more accessible to everyone.
I have the feeling that many of us forget about the value of this, after having invested many hours to understand complex syntaxes and general patterns.
From lowering the entry barrier and increasing efficiency, everybody will profit in the end.
It's always interesting how something that shouldn't be that big of a deal is a much bigger deal when experienced. I mean that using Markdown is not conceptually different than writing judiciously-placed block comments, but the ease of formatting for the coder -- and the most definite impact on reading for the reader -- is a huge impact. Thinking about it now, I sometimes skip self-documentation even when I know it's the right thing to do (given how much time we spend re-reading code compared to writing it) because it's annoying just enough to remember what my style/convention is to make long comments readable. Having Markdown provide the template removes that cognitive barrier, and hopefully makes it easier to ease into the documentation process.
I thought the `do loadManifesto' syntax was discouraged in favor of 'loadManifesto()'? I've read jashkenas say he wished that hadn't been introduced in the first place, and now I see it in his code.
Do you tell your editor to hard-wrap each "block" of comments as you write (or edit) them, or is your editor configured to automatically hard-wrap all comments?
Either way, have you considered configuring your editor to soft-wrap comments while leaving your code alone? I'd say that's the most natural approach from a writing standpoint.
P.S. Every day, I use tools you've made. Keep making!