[erlang-questions] Re: What about making sense?

[Richard O'Keefe]

On Feb 21, 2010, at 7:02 AM, Joe Armstrong wrote:

> I've been thinking about documentation/books for years now.
>
> One thing that documentation and books does not capture is the order  
> in
> which we write a program.
>
> A book with a code example presents the final result of a process. Not
> how we arrived at the result.

My PhD time at Edinburgh overlapped with Martin Feather.
http://delivery.acm.org/10.1145/360000/357154/p1-feather.pdf?key1=357154&key2=1839976621&coll=GUIDE&dl=GUIDE&CFID=77105502&CFTOKEN=60303561
A System for Assisting Transformation
MARTIN S. FEATHER
ACM Transactions on Programming Languages and Systems, Vol. 4, No. 1,  
January 1982, Pages 1-20.

The idea here was to specify a program in two pieces:
(a) a high level specification
(b) a transformation script that turned it into something more efficient
One idea was that if you changed the high level specification you should
be able to reuse most of the transformation script.
Another idea was that people should read the high level specification  
and
the script rather than the lower level code.

However, that started with a correct specification.

About the same time Ehud Shapiro came up with the idea of declarative
debugging, including the notion of creating a program by debugging an
empty program.  (This is _LONG_ before Fowler & co came along.)

There are also links with the Bird-Meertens school (which itself links
back to Dijkstra's "Discipline of Programming") of "calculating
programs from specifications".

>
> When I write *any* process I always start with something like:
>
> loop(...) ->
>    receive
>         Any -> io:format("got:~p~n",[Any]),
>         loop(...)
>   end.
>
> it's always the same. I then run the program and see what messages
> arrive at the receive loop. I then add patterns that match the  
> messages
> that arrive.
>
> As I develop the program I work in small steps - adding one message  
> at a time
> and testing as I go. When I'm ready and the program is developed I  
> might
> remove the "Any -> ..." bit.
>
> Seeing the final result give no clues as to the order in which  
> things were
> done. Each micro step can have a deal of thinking behind it.

Xerox PARC used to have a slogan, "A program is not a listing".
(By which they meant "a program is a database", hence the Smalltalk
and Interlisp IDEs.)  A program is, it would appear, a _temporal_
database, and the _transitions_ are as much deserving of record and
comment as the _states_.
>
> Can this be described in words at all? - I doubt it. I really like  
> Utube videos
> that explain how to do things in some domain. You can stop and  
> replay them.
> A video with a detailed commentary seems then best way to do this.

But (a) they are much MUCH more costly for people on the other side of  
the
world to access than text.  Downloading a single one-hour lecture from  
the
SICP series showed up on my department's budget and was raised at a
departmental meeting as an issue.  And (b) they are painfully SLOW to
watch.  Don't forget (c): what the presenter saw as an issue that needed
explaining might be obvious to some viewers, while what a viewer has
serious trouble with might be obvious to the presenter.  Imagine, for
example, someone presenting an Erlang chat system and labouring over
details of Erlang syntax while taking mnesia for granted.

> Books - and printed documentation - no matter how good - cannot  
> illustrate
> process - *the exact order in which I did things any why*

Books _can_ illustrate process, although not perhaps at the micro-level
of keystrokes.  They can certainly show a series of versions with
commentary.
>
>
> I greatly sympathises with those who say "I can't understand
> documentation". Documentation is written for those who already
> understand - and is no a vehicle for understanding itself.

On the other hand, I *did* learn Unix V7 from the manuals and nothing
else, and Ada 81 (and up to Ada 95) from the LRM and nothing else.
For some kinds of material, books can do very well indeed.
>
>
> "Read the code Luke" is even worse - even If I could understand the  
> code
> (which can sometimes be *extremely* difficult) I have not idea at all
> what it is *supposed* to do  only what it does. I consider this
> unprofessional.

It's not without interest that Squeak, the open source incarnation of
Smalltalk-80, where the "read the source" slogan found an early home,
now nags people with red "THIS CLASS HAS NO COMMENT" warnings.
>
Aside from the books, which are really good, I think the "greatest"
piece of Erlang documentation is the "OTP Design Principles Users
Guide".  It's certainly the most critical to read, which is why it's
a pity that it's not really obvious in the on-line documents.  It's
not mentioned at all in http://www.erlang.org/doc/ for example, and
I've have listed it near the language reference.