[Squeakfoundation]Re: Proposal for TWO official releases

[Maarten Maartensz]

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=F6ran 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=F6ran'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=20
>    B. Learning & Teaching release...

Regards,

Maarten.


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