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