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/ ------------------------------------------