7 ms·

A new way to think about programs

130 points by mrduncan 16y ago

rbxbx 16y ago
A new implementation of a way to think about programs may be a more accurate title. Quite enjoyed the article though, plus anything giving coffeescript love has my vote.
- deleted 16y ago
  [deleted]
- nswanberg 16y ago
  Luke Gorrie created a tool to format program listings for paper using emacs: http://fresh.homeunix.net/~luke/misc/emacs/pbook.el http://fresh.homeunix.net/~luke/misc/emacs/pbook.el Here's a rendered example of using the program on itself: http://discontinuity.info/~pkhuong/pbookc.pdf http://discontinuity.info/~pkhuong/pbookc.pdf
  - kenjackson 16y ago
    The rendering seems pretty good. The prose needs some work though. It was only marginally more useful than relatively sparse comments. Didn't seem to add the value I was expecting.
steveklabnik 16y ago
I'd seen a few of these pages before, but never known what they were called. I've also heard of literate programming, but never given it a real shot. Combine that with a recent effort to write more, and this all seems right up my alley. Super cool.
jashkenas 16y ago
For folks wondering about what the "CoffeeScript is about to get even more interesting" bit is about, it's just the past month of changes since 0.9.4, which are considerable indeed: https://github.com/jashkenas/coffee-script/compare/0.9.4...master https://github.com/jashkenas/coffee-script/compare/0.9.4...m... If this article inspires you to get started, and you don't mind doing a little bit of legwork to figure out syntactic changes, I'd recommend starting with master instead of 0.9.4.
- ivanzhao 16y ago
  When do you estimate 1.0 will be out? (Great work by the way.)
  - jashkenas 16y ago
    When it reaches it's first anniversary... It'll be under the tree by Christmas Eve.
agl 16y ago
Literate programming, at least at Knuth defines it, includes some aspects which Docco omits. Firstly, the machine readable file can be output in a different order than the human readable. (Indeed, sequential chunks in the human readable output can be directed to multiple different files.) Secondly, the human readable file includes 'outlining': when describing a function, parts of it can be elided and covered later. Now, these may have been required because the target language was C(like), which has different properties from many other languages. But I did want to point out that Docco is a quite different point in the literate programming landscape. For examples, see a couple of literate programs that I've written. With Web (Knuth's tool): https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pdf https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pd... With my own tools: http://www.imperialviolet.org/binary/lsmsb.html http://www.imperialviolet.org/binary/lsmsb.html
- pufuwozu 16y ago
  Literate Haskell seems to minimise the first difference (Haskell allows you to define functions out of order). I'm not familiar with outlining. Does anyone have a simple example?
  - ch 16y ago
    Check out 'libavl' which was written in the literate programming style: http://www.stanford.edu/~blp/avl/libavl.html/ http://www.stanford.edu/~blp/avl/libavl.html/
- jashkenas 16y ago
  Fortunately, in most modern languages, functions can be defined in any order -- and baseline configuration can be included in a separate file. In this day and age, generating the machine-readable version of the file in a different order than the version that is meant to be read, seems like an unnecessary convolution and debugging hurdle.
  - DougWebb 16y ago
    Not necessarily. I can see some value in having a different organization for explaining the program to someone new to it vs organizing it to make it easy to maintain for someone familiar with it. For example, for maintenance you'd like to have all of your constants defined together and usually near the top, but for documenting you'd probably prefer to introduce constants when they're needed.
FooBarWidget 16y ago
If an exception is thrown in a Coffeescript program, does the runtime correctly report the original Coffeescript line numbers instead of that of the compiled Javascript? Things like this are the main reason why I'm wary of compilers that compile to another high-level language.
- dreyfiz 16y ago
  In practice, this isn't a problem. Coffeescript is more of an alternate syntax for Javascript than a different language. Sure it has some great sugar, but it's really easy to understand how that sugar translates into plain old Javascript. I'll usually have the .js file sitting in the next tab, being compiled live as I write code in the .coffee tab and hit save. Work like this for a little while and you'll learn to recognize which javascript is generated from which coffeescript really efficiently. coffee -cw -o js/ coffee/ Plus, your variable names in Coffeescript are well-preserved in the generated JS. Ultimately I find it harder to follow exceptions in my production javascript because of the obfuscation caused by minification (I use yuicompressor), so on my staging and development servers I point to a non-minified .js. Bottom line: try it, you'll like it!
- dpritchett 16y ago
  Your errors list JS line numbers. I didn't find it very difficult to mentally map the JS errors back to my Coffee source though - you get the same program structure and variable/method names before and after compile. Let's say you found a bug in line 41 of my JS source here: https://github.com/dpritchett/chatbox/blob/master/public/chatbox.js#L39 https://github.com/dpritchett/chatbox/blob/master/public/cha... Digging into the Coffee source shows the same short method with all the same identifiers and the same basic structure... just less boilerplate: http://dpritchett.github.com/chatbox/docs/chatbox.html#section-11 http://dpritchett.github.com/chatbox/docs/chatbox.html#secti...
  - dreyfiz 16y ago
    Aha, your answer is more concise, and it addresses FooBarWidget's misapprehension more directly. Yes, "the runtime" is just the browser javascript engine.
grayrest 16y ago
One of the more unique programming approaches I've come across is the Leo editor, which was written to support literate programming but also functions as an outliner. When you're working with Leo, you work with a tree of text nodes instead of working with explicit files/directories. Because the nodes exist in an always visible tree, the natural inclination is to label the node with what the code inside does. This subtly enforces literate programming. This is good, but what makes Leo novel is the nodes can be cloned (think hard symlink) and then rearranged however you like. You can put a node containing a function's unit tests and another containing its documentation as children of the node containing the function. When fixing a bug, you can create a node that points to the issue's url in your bug tracker and then clone all related nodes as children for both documentation and convenience when you're working on the bug. When working on frontend code, you can clone nodes for related js/html/css for conveniently switching between them. It's very cool. Unfortunately, it's not really practical to use it as your primary editor. Ed serializes/deserializes the nodes to files using sentinels in comments, so the output files tend to wind up with a lot of "junk" comments. I also missed the Vim command grammar a lot.
- fanf2 16y ago
  This sounds like the inmos transputer development system and the various editors that descended from it.
tomjen3 16y ago
This isn't actually literate programming as Knuth defines it (If you read his 1984 paper, he specifically talks about _writing the code in such as way as to inform the programmer about what you want the computer to do_, which means that you write the code and documentation at the same time. In addition the literate programming tools that came from Knuths original all allow you to order the in the order you find makes sense -- not in the other required by the compiler. This, while very interesting, is much, much closer to Elucidative programming[1], which is less well known but is also properly easier to get started with. [1]http://www.cs.aau.dk/~normark/elucidative-programming/index.html http://www.cs.aau.dk/~normark/elucidative-programming/index....
another_ali 16y ago
"Going from Javascript to Coffeescript today feels a lot like going from Java to Ruby felt to me in early 2003." One should really wonder, why did he skip on Python, Perl and Ruby for all those years? Knowing that RoR appeared in 2004, and thinking that Coffeescript seems closer to Python
tzs 16y ago
We did something similar we did when the company I work for specialized in consulting, back in the late '80s. At the end of a project, one of our deliverables was usually something we called "left hand pages". It consisted of a binder with a complete listing of the source code we produced for the client, with the source code printed on the right hand pages. On the left hand pages was a detailed commentary and explanation of the corresponding right hand code. Extra space would be inserted in the right as necessary to make room for the left hand commentary. We would not skimp on the left. The commentary was aimed at being all a new programmer at the client would need to take over maintenance and enhancement of the software. It was assumed he knew the language, and had a copy of and understood the hardware specs. Of course, hardware specs often deviate from what the hardware actually does, and we'd cover all those oddities and deviations in the left hand pages.
- rbanffy 16y ago
  How do you keep both sides in sync? Special comments in the source that get printed as left-hand pages and suppressed from the right-hand ones?
  - tzs 16y ago
    It was pretty low tech. I seem to recall we'd do something like write the left hand pages in a word processor, then we'd use the page preview mode to see how the pagination of that was going to work out. We'd make a copy of the source code in a text editor, and insert blank lines as appropriate to get it to line up reasonably. Then I believe we'd print the left hand pages on the laser printer, turn the sheets over, and print the source code.
dpritchett 16y ago
Jeremy Ashkenas (creator of Coffeescript and of docco) is uniquely positioned as an expert in accessible technology. See his hypertext visualization of his thesis project or the various visualizations of government data in his portfolio. He works at DocumentCloud on similar themes. http://ashkenas.com/ http://ashkenas.com/
adriand 16y ago
The pseudocode programming process (PPP) described in Code Complete strikes me as quite similar to the concept of literate programming. In PPP the idea is to start with pseudocode in the form of source code comments that start with a very high-level overview of the task being accomplished, written in plain English (or whatever human language), which is then broken down into smaller and smaller constituents. When the explanation can no longer be decomposed, the actual code is written. That approach seems like it would suit the literate programming style very well, and in particular would make the documentation generated by Docco easy to read and comprehensive. That said, I've never really used PPP and prefer TDD instead.
crasshopper 16y ago
I don't get it. I've read MozDev's Re-Introduction to Javascript and the coffeescript looks just as clean.

130 points by mrduncan 16y ago

rbxbx 16y ago

A new implementation of a way to think about programs may be a more accurate title. Quite enjoyed the article though, plus anything giving coffeescript love has my vote.

deleted 16y ago
[deleted]
nswanberg 16y ago
Luke Gorrie created a tool to format program listings for paper using emacs: http://fresh.homeunix.net/~luke/misc/emacs/pbook.el http://fresh.homeunix.net/~luke/misc/emacs/pbook.el Here's a rendered example of using the program on itself: http://discontinuity.info/~pkhuong/pbookc.pdf http://discontinuity.info/~pkhuong/pbookc.pdf
- kenjackson 16y ago
  The rendering seems pretty good. The prose needs some work though. It was only marginally more useful than relatively sparse comments. Didn't seem to add the value I was expecting.

steveklabnik 16y ago

I'd seen a few of these pages before, but never known what they were called. I've also heard of literate programming, but never given it a real shot. Combine that with a recent effort to write more, and this all seems right up my alley. Super cool.

jashkenas 16y ago

For folks wondering about what the "CoffeeScript is about to get even more interesting" bit is about, it's just the past month of changes since 0.9.4, which are considerable indeed: https://github.com/jashkenas/coffee-script/compare/0.9.4...master https://github.com/jashkenas/coffee-script/compare/0.9.4...m... If this article inspires you to get started, and you don't mind doing a little bit of legwork to figure out syntactic changes, I'd recommend starting with master instead of 0.9.4.

ivanzhao 16y ago
When do you estimate 1.0 will be out? (Great work by the way.)
- jashkenas 16y ago
  When it reaches it's first anniversary... It'll be under the tree by Christmas Eve.

agl 16y ago

Literate programming, at least at Knuth defines it, includes some aspects which Docco omits. Firstly, the machine readable file can be output in a different order than the human readable. (Indeed, sequential chunks in the human readable output can be directed to multiple different files.) Secondly, the human readable file includes 'outlining': when describing a function, parts of it can be elided and covered later. Now, these may have been required because the target language was C(like), which has different properties from many other languages. But I did want to point out that Docco is a quite different point in the literate programming landscape. For examples, see a couple of literate programs that I've written. With Web (Knuth's tool): https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pdf https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pd... With my own tools: http://www.imperialviolet.org/binary/lsmsb.html http://www.imperialviolet.org/binary/lsmsb.html

pufuwozu 16y ago
Literate Haskell seems to minimise the first difference (Haskell allows you to define functions out of order). I'm not familiar with outlining. Does anyone have a simple example?
- ch 16y ago
  Check out 'libavl' which was written in the literate programming style: http://www.stanford.edu/~blp/avl/libavl.html/ http://www.stanford.edu/~blp/avl/libavl.html/
jashkenas 16y ago
Fortunately, in most modern languages, functions can be defined in any order -- and baseline configuration can be included in a separate file. In this day and age, generating the machine-readable version of the file in a different order than the version that is meant to be read, seems like an unnecessary convolution and debugging hurdle.
- DougWebb 16y ago
  Not necessarily. I can see some value in having a different organization for explaining the program to someone new to it vs organizing it to make it easy to maintain for someone familiar with it. For example, for maintenance you'd like to have all of your constants defined together and usually near the top, but for documenting you'd probably prefer to introduce constants when they're needed.

FooBarWidget 16y ago

If an exception is thrown in a Coffeescript program, does the runtime correctly report the original Coffeescript line numbers instead of that of the compiled Javascript? Things like this are the main reason why I'm wary of compilers that compile to another high-level language.

dreyfiz 16y ago
In practice, this isn't a problem. Coffeescript is more of an alternate syntax for Javascript than a different language. Sure it has some great sugar, but it's really easy to understand how that sugar translates into plain old Javascript. I'll usually have the .js file sitting in the next tab, being compiled live as I write code in the .coffee tab and hit save. Work like this for a little while and you'll learn to recognize which javascript is generated from which coffeescript really efficiently. coffee -cw -o js/ coffee/ Plus, your variable names in Coffeescript are well-preserved in the generated JS. Ultimately I find it harder to follow exceptions in my production javascript because of the obfuscation caused by minification (I use yuicompressor), so on my staging and development servers I point to a non-minified .js. Bottom line: try it, you'll like it!
dpritchett 16y ago
Your errors list JS line numbers. I didn't find it very difficult to mentally map the JS errors back to my Coffee source though - you get the same program structure and variable/method names before and after compile. Let's say you found a bug in line 41 of my JS source here: https://github.com/dpritchett/chatbox/blob/master/public/chatbox.js#L39 https://github.com/dpritchett/chatbox/blob/master/public/cha... Digging into the Coffee source shows the same short method with all the same identifiers and the same basic structure... just less boilerplate: http://dpritchett.github.com/chatbox/docs/chatbox.html#section-11 http://dpritchett.github.com/chatbox/docs/chatbox.html#secti...
- dreyfiz 16y ago
  Aha, your answer is more concise, and it addresses FooBarWidget's misapprehension more directly. Yes, "the runtime" is just the browser javascript engine.

grayrest 16y ago

One of the more unique programming approaches I've come across is the Leo editor, which was written to support literate programming but also functions as an outliner. When you're working with Leo, you work with a tree of text nodes instead of working with explicit files/directories. Because the nodes exist in an always visible tree, the natural inclination is to label the node with what the code inside does. This subtly enforces literate programming. This is good, but what makes Leo novel is the nodes can be cloned (think hard symlink) and then rearranged however you like. You can put a node containing a function's unit tests and another containing its documentation as children of the node containing the function. When fixing a bug, you can create a node that points to the issue's url in your bug tracker and then clone all related nodes as children for both documentation and convenience when you're working on the bug. When working on frontend code, you can clone nodes for related js/html/css for conveniently switching between them. It's very cool. Unfortunately, it's not really practical to use it as your primary editor. Ed serializes/deserializes the nodes to files using sentinels in comments, so the output files tend to wind up with a lot of "junk" comments. I also missed the Vim command grammar a lot.

fanf2 16y ago
This sounds like the inmos transputer development system and the various editors that descended from it.

tomjen3 16y ago

This isn't actually literate programming as Knuth defines it (If you read his 1984 paper, he specifically talks about _writing the code in such as way as to inform the programmer about what you want the computer to do_, which means that you write the code and documentation at the same time. In addition the literate programming tools that came from Knuths original all allow you to order the in the order you find makes sense -- not in the other required by the compiler. This, while very interesting, is much, much closer to Elucidative programming[1], which is less well known but is also properly easier to get started with. [1]http://www.cs.aau.dk/~normark/elucidative-programming/index.html http://www.cs.aau.dk/~normark/elucidative-programming/index....

another_ali 16y ago

"Going from Javascript to Coffeescript today feels a lot like going from Java to Ruby felt to me in early 2003." One should really wonder, why did he skip on Python, Perl and Ruby for all those years? Knowing that RoR appeared in 2004, and thinking that Coffeescript seems closer to Python

tzs 16y ago

We did something similar we did when the company I work for specialized in consulting, back in the late '80s. At the end of a project, one of our deliverables was usually something we called "left hand pages". It consisted of a binder with a complete listing of the source code we produced for the client, with the source code printed on the right hand pages. On the left hand pages was a detailed commentary and explanation of the corresponding right hand code. Extra space would be inserted in the right as necessary to make room for the left hand commentary. We would not skimp on the left. The commentary was aimed at being all a new programmer at the client would need to take over maintenance and enhancement of the software. It was assumed he knew the language, and had a copy of and understood the hardware specs. Of course, hardware specs often deviate from what the hardware actually does, and we'd cover all those oddities and deviations in the left hand pages.

rbanffy 16y ago
How do you keep both sides in sync? Special comments in the source that get printed as left-hand pages and suppressed from the right-hand ones?
- tzs 16y ago
  It was pretty low tech. I seem to recall we'd do something like write the left hand pages in a word processor, then we'd use the page preview mode to see how the pagination of that was going to work out. We'd make a copy of the source code in a text editor, and insert blank lines as appropriate to get it to line up reasonably. Then I believe we'd print the left hand pages on the laser printer, turn the sheets over, and print the source code.

dpritchett 16y ago

Jeremy Ashkenas (creator of Coffeescript and of docco) is uniquely positioned as an expert in accessible technology. See his hypertext visualization of his thesis project or the various visualizations of government data in his portfolio. He works at DocumentCloud on similar themes. http://ashkenas.com/ http://ashkenas.com/

adriand 16y ago

The pseudocode programming process (PPP) described in Code Complete strikes me as quite similar to the concept of literate programming. In PPP the idea is to start with pseudocode in the form of source code comments that start with a very high-level overview of the task being accomplished, written in plain English (or whatever human language), which is then broken down into smaller and smaller constituents. When the explanation can no longer be decomposed, the actual code is written. That approach seems like it would suit the literate programming style very well, and in particular would make the documentation generated by Docco easy to read and comprehensive. That said, I've never really used PPP and prefer TDD instead.

crasshopper 16y ago

I don't get it. I've read MozDev's Re-Introduction to Javascript and the coffeescript looks just as clean.