Re: Examples in Docs, was Re: Escape Sequences in Strings

[Brian Rogoff <bpr@shell5.ba.best.com>]

On Thu, 18 Jan 2001, Robert Dewar wrote:
> In article
> <Pine.BSF.4.21.0101170815001.21897-100000@shell5.ba.best.com>,
>   Brian Rogoff <bpr@shell5.ba.best.com> wrote:
> > I wonder if you learned SML programming from "The Definition
> > of Standard ML" :-).
> 
> Yes, it's the only document I ever read to learn ML.

Well, I am in awe. If I remember correctly, there are a few important
aspects of SML programming, like evaluation order, that are not
explicitly stated but have to be deduced. I can't imagine anyone getting a 
feel for how to program in ML from the definition, especially if they were 
not familiar with functional programming style.  

> > Seriously, I'm pretty amazed that anyone can learn to program
> > from a  typical language spec without examples. Do you think
> > it is a learnable  and teachable skill (do you teach your
> > students this?), or is it a unique quirk?
> 
> Well certainly it helps to have a lot of experience in looking
> at different language designs.

When you started your career as a language researcher, did you learn from 
language specs? I realize that this is a bit off topic for the ng, but I 
can always find a way to relate it to Ada :-) if people complain. 

> I don't think it is a quirk by any means. After all a
> mathematician does not need examples of what a proof is
> talking about.

I agree, but I think mathematics is quite a bit different from
programming, and I have a decent background in both. (Note to 
RBKD: that's why I chose SML as an example, since it's definition is 
the most "mathematical" of any well known current programming language).
If we look at the history of certain ideas in mathematics, say the 
foundations of the infinitesimal calculus (*), we see that the progress 
is from examples to rules, not the other way around. I learned counting
from examples before I learned Peano's Axioms. 

Bourbaki /= good pedagogy

> Examples can never tell you what the general rules are, they
> can only illustrate particular cases, and therefore there is
> a danger of not understanding the generalization.

I agree with this. That's why I like to have a reference manual at my side 
when I'm learning. However, I've found that like most people I learn best 
by example. I personally detest the analogy between programming languages 
and human languages, since any good Chomskyan will tell you we have hard
wiring for the latter, but I suspect that even you Robert learned your
native language by generalizing incorrectly from examples.
 
> Certainly a BNF grammar is a FAR clearer documentation of
> syntax than syntactic examples, wouldn't you agree?

Of course! However, when I learn a new programming language, to get an
idea of the syntax I look at a few representative examples first. That
allows me to get an idea if the syntax is familiar. Here is a rough cut at
some language syntax "classes" where I've grouped languages into
*synatactically" similar groups:

Algol: Pascal, Modula-<X>, Oberon-<X>, Ada, Dylan
C : C++, Objective-C, Java, C#
Lisp: Scheme, Emacs-Lisp, Common-Lisp...
Prolog: Erlang, Mercury
Haskell: Clean, Python, OCCAM ("offset rules")
ML: SML, OCaml

While I'm not intimately familiar with all of these languages, a quick
glance at new language examples allows me to categorize it (or not!) and 
I find that I can get up to speed *on syntax* quickly. Then, afterwards, I 
go to the BNF. I take it that you just go straight to the BNF and skip 
the examples altogether.

The reason I asked if you teach your way, and if students are receptive, 
is that I'd be interested in trying it myself. In fact, I'll try this
with the next PL I learn. 

-- Brian

(*) Yes, I deliberately used "infinitesimal". I'm a rebel. The theory of 
    limits is oppressive, and infinitesimals came first. Non-standard 
    analysis rules :-)