[Squeakfoundation]Re: Proposal for TWO official releases

[Maarten Maartensz]

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."

And similarly in ALL the other cases of "I am ..." ALL of which (1) make a
piece of comment present itself as animated entity (2) that mistakenly
describes itself as the code it attempts to comment (and very misleadingly
suggests a piece of code running on a computer is or could be a living
entity).

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").

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. 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) ..."?

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. 

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 and the non-existence or
unclarity of good comments to otherwise good code.

><snip>
>
>Joshua

Regards,

Maarten.


------------------------------------------
Maarten Maartensz. Homepage:
http://www.xs4all.nl/~maartens/ 
------------------------------------------