[Squeakfoundation]Re: Proposal for TWO official releases

[Joshua 'Schwa' Gargus]

On Sat, Apr 20, 2002 at 01:47:22PM +0200, Maarten Maartensz wrote:
> Hello Joshua,
> 
> At 01:39 20-4-02 -0400, you wrote:
> 
> >On Fri, Apr 19, 2002 at 08:31:03PM +0200, Maarten Maartensz wrote:
> >> Hello Carl,
> >> 
> >> At 08:57 19-4-02 -0700, you wrote:
> >> 
> >
> ><snip suggestion to accept only documented code>
> > 
> >> I have less than 1/14th of your experience with Smalltalk (but 14 years
> >> with Prolog, mostly, from which I have drawn a similar lesson about
> >> documenting and commenting code), but my initial reaction is: This sounds
> >> like a GREAT idea!
> >
> >I like it as well.
> 
> Good.
> 
> ><snip>
> >
> >> O, and please do not write Comments on the line of "I (this piece of
> >> comment on this piece of code) am ... " etc. For this is just categorical
> >> nonsense: Prose is not animated. 
> >
> >I have no problem with classes commenting on themselves in the first
> >person.  I think that it encourages you to think in an object-oriented
> >manner.
> 
> I do have serious problems here. Indeed, I believe one of the reasons
> Smalltalk is less popular and less well known than it should be is just
> this style of writing about it. Now I am sure this is in fact a large
> topic, so I just give one brief example from very many: Here is the first
> statement of the Class Number (and the rest of the Comment doesn't make
> things clearer for a newbie, and also not for newbies with lots of
> mathematical knowledge):
> 
> "I am an abstract representation of a number."
> 
> Taken literally - and if one describes code, this seems a fair approach:
> code is a kind of text - here we have, it would seem from the very words
> used, THE Platonic Form Number Itself personally expounding the deepest
> Pythagorean Mysteries. Now whatever thinking "in an object-oriented manner"
> means, it should not mean having to write nonsensical, metaphysical or
> theological English.
> 
> Take the just the initial two words "I am" that occur likewise in many
> Comments: What IS meant but NOT said is: "The code this comment is about is
> intended to ...". (Note that a Comment in Smalltalk IS a piece of text
> explaining a piece of code.) 
> 
> Now what is wrong ("non-object oriented"?) about writing e.g. instead:
> 
> "(The Class) Number consists of the most general methods for dealing with
> numbers."
> 

Nothing is wrong with it, and I agree that this is much better than
the existing comment, but not because you replaced the "I am".

"I specify the most general methods for dealing with numbers." 

is, in my opinion, just as good as your comment.  It is certainly better than:

"(The Class) Number is an abstract representation of a number".


> And similarly in ALL the other cases of "I am ..." ALL of which (1) make a
> piece of comment present itself as animated entity

No, the piece of comment presents the _class_ as an animated entity.
When I write "I am a human", the paper I write it on is not saying
that it is a human.  It is communicating on behalf of another entity,
me.  Similarly, a class comment is communicating on behalf of the
class.  I personally have had no problems with this, right from the
first time I started Squeaking.

> (2) that mistakenly
> describes itself as the code it attempts to comment

I suppose that this is true if you consider a class to be nothing more than
code (which is correct, in a certain sense).  However, a class might also 
be understood as a platonic concept.

> (and very misleadingly
> suggests a piece of code running on a computer is or could be a living
> entity).

I suppose that it does.  Again, I don't see a problem.  What about
MorphicWrappers, where you type over a morph to send it a message
directly.  You are talking directly to it, and it answers directly.
This is an interesting UI approach that anthropomorphizes the objects
in the system to an even greater degree than a static class comment.

Are you suggesting that people might become confused about this point, and
believe that the computer is alive?  This might be a valid criticism if
EToys were to present itself in this way, but presumably by the time you
are hacking Smalltalk, you understand computers well enough to recognize
this as a manner of speaking.

> A Comment to a piece of code should be in clear English and not make all
> manner of irrelevant or false assumptions (perhaps suggested by hitherto
> unrealized ideals like "a Smalltalk object is - or is like - a living
> entity that inhabits a computers' memory").

This sort of language has been with Smalltalk from the beginning, as far
as I can tell.  For example, when you send an object a message, it doesn't
"return" a value, it "answers" you.  It seems to have been a conscious
decision by the creators of Smalltalk.

> However, I am sure there is a large and sensitive theme here, and I for my
> part feel sure that one major reason for Smalltalk having less of a
> following than it deserves is the way Smalltalkers write about code. 

I doubt that this is a major reason.

> To me
> it would seem that in part this is justified by the way Smalltalk is
> different from other languages, but mostly it is just not good English. And
> it should be possible to explain code without writing what amounts to
> (rather wild) metaphysics or theology, and in any case is wildly
> misleading. After all, who would seriously start an e-mail with "I am an
> e-mail that (is an abstract representation of) ..."?
> 

Nobody, because the email is a communication from you, not a self-referential
piece of text.

> However, having partaken in other theological and metaphysical debates
> about other subjects entirely .... what I am not at all sure about is
> whether it makes sense to discuss this theme on this or another maillist. 
> 
> But yes: This is one of MY major gripes about Smalltalk: The CODE is
> beautiful, but it is often talked about in VERY misleading animistic and
> metaphorical English, that is totally unnecessary. 

Unnecessary, yes.  Whimsical, yes.  Problematic, no, not in my opinion.

> 
> What converted me to Smalltalk and Squeak is the code itself plus the
> coding environment; what made this FAR more difficult than necessary are
> the style of talking about Smalltalk code 

As I've stated, I see no problem, and actually find the style a bit quirky
and appealing.  However, if it is generally perceived as a stumbling block
for newbies, then I will not dogmatically insist that we should continue
to write this way.  Again, I have _never_ found this style confusing.

> and the non-existence or
> unclarity of good comments to otherwise good code.

This is an entirely different issue.  I agree with you whole-heartedly.

Best,
Joshua


> ><snip>
> >
> >Joshua
> 
> Regards,
> 
> Maarten.
> 
> 
> ------------------------------------------
> Maarten Maartensz. Homepage:
> http://www.xs4all.nl/~maartens/ 
> ------------------------------------------
> 
> _______________________________________________
> Squeakfoundation mailing list
> Squeakfoundation@lists.squeakfoundation.org
> http://lists.squeakfoundation.org/listinfo/squeakfoundation