Comments on the "Distributed Smart Contracting..." document

Bill Frantz
Tue, 17 Nov 1998 12:46:46 -0800

For the most part, I found this document easy to read and understand.  Nice
job MarkM.

P11. "If the escape-hatch is not called, then the body expression completes
normally, and its value is the value of the escape expression."  I had to
read, "and its value is the value of the escape expression." several times
before I could figure out what the sentence meant.  A clearer version might
say, "... and the value of the body expression becomes the value of the
escape expression."  Or, "... and the value of the escape expression is the
result of evaluating the body expression."  YMMV  Also, what if the body
expression throws?  Perhaps it should say, "... called, and the body ..."
instead of "... called, then the body ...".

P13. I think talking about what these things expand into is a positive
good.  I couldn't for the life of me figure out how to build while out of
an escape/loop.  Seeing the example showed me that you couldn't.  It takes
two escapes.  Escape is an "exotic" concept.  Take a bit of time with it.
Examples are good.

p17. In the example at the bottom of the page (average), if you don't trust
"sample" or it is dynamic, the example should count the number of samples
rather than relying on "samples size".  It's probably good to have the
examples be defensive.

p18.  *** if you iterate on a mutable thing...  This point will need a code
example to show where the snapshot is taken and what it's scope is.  Will
it fix the problem with a mutable "samples" in the previous comment?

p24.  The last paragraph says, "The model is born not knowing about the
view or model."  Shouldn't the last word be "controller", not "model"?

p27.  I think it needs a better transition when resuming the "distance"
example.  Perhaps moving the getterSetterPair example?

p29. The second paragraph ends with, "The value of the method expression is
the value of the call."  I think this would be clearer as, "The value of
the call is the result of evaluating method-expression."

p37. Why are they called Miranda Methods?  I thought Miranda gave you the
right to remain silent.

In the spirit that the rules of user manuals are the exact opposite of the
rules of academic discourse, (For user manuals, never use a polysyllabic
word when a short one will do.), I have rewritten the first paragraph of
"The if expression".

   if (<test-expression>) {
   } else {

The if expression first evaluates <test-expression>.  If its value can not
be cast to a boolean, a to-be-specified exception is thrown.  Otherwise if
its value is true, <then-expression> is evaluated.  Otherwise (its value is
false), <else-expression> is evaluated.  The value of the if-expression is
the result of the expression which was evaluated.