Hello Carl,
At 08:57 19-4-02 -0700, you wrote:
As laudable a goal as a simpler/better documented image is, I think the extra work that comes with duplication of release streams will probably mean your proposal won't capture enough support.
You may be right, but I hope to achieve something this direction when SqueakFoundation gets finally incorporated. And if nobody tries, nothing much will happen. But I cannot do it alone, and few on the list can.
In my 14 years in Smalltalk the only mechanism I've seen work that leads
to well documented classes/messages is a rule by the image builder that a change file is ONLY accepted IF it leaves EVERY class touched by the changes FULLY documented (class + message comments). This causes a lot of cursing and swearing initially because it means to change even a single method you have to take on commenting the entire class. But its amazing how quickly the image gets documented, how much obsolete code gets found and removed, how many bugs are noted and fixed, and how quickly the system becomes more easily usable, reusable, and maintainable because the system is more understandable.
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!
So I ask others - including the proverbial gurus and the Harvesters - for their comments for this idea:
Wouldn't it be wise - seeing also the state of even VW's comments! - to make it an absolute rule for the Harvesters to accept ONLY code with proper comments and at least one example, and to announce this publicly and insist on it? (If necessary, I could quote Donald Knuth on your and my side: He called this "literate programming". And as Göran pointed out, in a mail on the developer's list, and as I had found myself meanwhile, even such a fundamental Class as Set is without comment!)
Once the classes are documented as such and a system for naming method protocols is followed, I wrote an object that traversed target classes and a produced cross-referenced HTML pages documenting the public interfaces of the classes. Being able to instantly view the commented public interface for a class immensely helped reusability and respect for the public/private interface division.
Yes, I can well imagine it. I tend to learn by FAR the most using the diverse browsers and explorers and by studying the code, but one of my standard complaints is: O, this could have been SO much easier and quicker to understand if only the maker had provided a clear English comment and one or two good examples of the intended use.
This is also why I am MUCH in agreement with Göran's campaign to - I think the word is - "refactor" the Class Comments, and I hereby call on all Squeak gurus to do their bit there so that the official 3.2 release can, probably for the first time in 30 years of Smalltalk (!!), come with good Comments and Examples for all classes.
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. Simply name the code you comment on by its name, and tell what it is intended to do, what it uses and presupposes, and give an example for its use, and don't introduce very odd idiosyncratic and metaphysical English, that also has no clear point or sense whatsoever.
Carl Gable Watts
Maarten Maartensz wrote on 18/4/02 5:00 pm:
...I'd propose the following to both Squeak.org and the Squakfoundation:
- To maintain TWO releases as a standard policy: A. Developers' release B. Learning & Teaching release...
Regards,
Maarten.
------------------------------------------ Maarten Maartensz. Homepage: http://www.xs4all.nl/~maartens/ ------------------------------------------