[E-Lang] E Project, Documentation, and new programmers

[Marc Stiegler]

> [1]  For a case in point, after my first foray into using E, I think that
the
>  default ":none" guard is a major source of surprises that leave newbie
>  programmers unable to figure out what went wrong, and that it really
ought to
>  be changed to a default ":retAny" guard that returns anything wrapped in
a
>  "RetVal" object.  I will soon publish my notes about that experience.

I don't want to prevent you from publishing your notes, but from this brief
bit I can already make several observations and a counterproposal:

1) I too, from firsthand experience, agree that the :void default return
from functions and methods creates surprises. It is still a surprise for me
occasionally even though I am a "seasoned" E programmer, and it was worse
when the :void default was brand new for me.

2) A :any default is a security disaster. We've been there, done that,
burned our fingers off. We are currently negotiating about immutable
collections because of the security issues with mutable collections. Well,
the :any default is hundreds, maybe thousands, of times more dangerous than
any kind of collection now under discussion. As I said at the time, "a
security oriented language simply cannot by default leak capabilities."

3) Having a special flag in E to switch to a :any default for newbies is an
upgrade disaster: if you thought the :void was hard to catch during
evolution of a program, wait till you throw that switch on a whole
"operational" program and watch the horror unfold. And I promise you that I
would never enable a :any return for any program someone handed to me (nor
should you). So such a switch would be a "broken the moment someone
expressed interest in using it" switch.

4) One of the things I have a note to write about in Walnut, which is not
there yet, is the E trace log. The ":void default when something was
supposed to come back" bug is generally easy to detect and to fix by reading
the trace log. I mention this for your own usage, it is not a complete
solution for the newbie.

5) So here is an alternative to a switch for enabling :any default. Instead
of having a method of enabling a  :any default, enable a method of detecting
no-default-allowed. Require explicit :void or :any or :something for every
method. This is the ultimate  way to ensure  no surprises. There are 2 ways
such explicit-return-required could be implemented.

One way is to put a flag on E. This is not very good for several reasons,
one of which is that the flag has to be per-file (the newbie will still be
using emakers written by others who probably did not use the
explicit-return-required convention).

The second way of detecting it would be to write a "lint" that could detect
functions and methods with no return value and warn the programmer. Such a
lint would be very easy to write, and could be attacked in many different
ways. I will mention 2 ways of writing it that are based on working in
eBrowser (and the 089t version of eBrowser is pretty cool, if you are doing
089t development and haven't tried it, you  should check it out. The one
serious flaw is that the class/function/variable outlines do not
automatically sync to the current text, you have to push a button. Automatic
synchronization is a feature that was working in the 089 eBrowser that is
turned off until we have comm again--the sync process must be placed in a
separate vat. On 089 I used to run the synchronization process on a
different computer on my network, though I reckon that on 0.8.10 we'll run
it in a separate vat on the same jvm :-).

The simplest thing to do would be to write an Elmer script that reads the
source and prints out the line numbers of the lines where a return guard was
expected; in eBrowser, you'd pop open a Scratchpad window and keep the code
there for running against the current file. The code for this lint script
could be based on the syncOutline method in eBrowser itself, which picks out
the function and method and class definitions and their line numbers. You'd
probably need about 3 more lines of code to detect and print the absence of
a guard between the parameter list close paren and the open brace. The
simplest version of this script would "hardwire" the target file, the way
the script I recently posted for checking for def'd variables that need to
be var'd does it. Slightly fancier would be to have it read the clipboard
(so do Ctrl-A Ctrl-C in the main browser window before running the script).
Clipboard handling E code can also be found in eBrowser, for the "Paste From
Scratchpad" function.

Fancier still would be to incorporate this lint into the "Run Program"
function, so that the lint runs every time you try to test the program. It
could abort the run operation and jump to the non-compliant line, the way
eBrowser now does for syntax errors. Or put an additional button on the
toolbar for running the lint checker.

Anyway, once someone has done a lint that serves one function like this, we
will have a basis for evolution of an E lint that could do lots of cool
analysis, not just for beginners but also for pros and for organizations
that want to enforce particular policies. It would be an exciting beginning
for a valuable piece of the E platform.

--marcs