
A new way to think about programs - mrduncan
https://github.com/raganwald/homoiconic/blob/master/2010/11/docco.md#readme
======
tzs
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
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
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.

------
agl
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.pd...](https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pdf)

With my own tools: <http://www.imperialviolet.org/binary/lsmsb.html>

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

~~~
tomjen3
Sure you can define the functions in pretty much any order, but can you define
two or more functions at the same time?

Say you are talking about the function to build the user interface, can you
stop defining that, go back and define the callback, then continue defining
the gui builder function?

Or, when you are writing an Android program, can you add stuff to the manifest
file, right as you write the source code that uses it?

Or, when you are writing that rails app, can you put the code for one of your
user stories, then extend your db model and finally add the code that test it
-- before you continue with the next user story that adds code to the same
controller?

~~~
anamax
> Say you are talking about the function to build the user interface, can you
> stop defining that, go back and define the callback, then continue defining
> the gui builder function?

That's how lisp folks worked. I don't see why that technique wouldn't work in
bare python as well.

Static type systems can make that difficult. How many frameworks impose
analogous constraints?

------
grayrest
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
This sounds like the inmos transputer development system and the various
editors that descended from it.

------
jashkenas
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...m...](https://github.com/jashkenas/coffee-
script/compare/0.9.4...master)

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
When do you estimate 1.0 will be out? (Great work by the way.)

~~~
jashkenas
When it reaches it's first anniversary... It'll be under the tree by Christmas
Eve.

------
tomjen3
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....](http://www.cs.aau.dk/~normark/elucidative-
programming/index.html)

------
dpritchett
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/>

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

~~~
nswanberg
Luke Gorrie created a tool to format program listings for paper using emacs:
<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>

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

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

~~~
dpritchett
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/cha...](https://github.com/dpritchett/chatbox/blob/master/public/chatbox.js#L39)

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#secti...](http://dpritchett.github.com/chatbox/docs/chatbox.html#section-11)

~~~
dreyfiz
Aha, your answer is more concise, and it addresses FooBarWidget's
misapprehension more directly. Yes, "the runtime" is just the browser
javascript engine.

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

------
adriand
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
I don't get it. I've read MozDev's Re-Introduction to Javascript and the
coffeescript looks just as clean.

------
another_ali
"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

