( picoVerse-:( Squeak documentation ) )

Hi squeak-dev list

( contents--
     ( The problem with Documentation )
     ( The easy FragmentMap solution )
     ( A question about loose methods in Squeak )
)

I find software documentation in general to be lacking.  somewhere
between lacking and abysmal.

Like this Prolog compiler I saw recently that used nothing but
single Character variable names and not one single comment
in the whole thing.  Just endless reams of short Prolog queries.
AquariusProlog.  It was supposed to be really great but I don't
see how anybody but the original programmer could maintain
it or adapt it.  Most software seems to be designed to rot quickly
once the original programmer moves on.

When the original programmer for this thing stops maintaining
it how can it do anything but die.

The only software that I thought was well documented was
Dolphin Smalltalk.  Each and every method in there had a
somewhat good comment in there and most of the important
Classes also had comments in them.  I found that I could figure
most things out without too much trouble and without asking
questions on the newsgroup.  Smalltalk/V was also good this
way.  With Squeak my first impression several times was that
I was totally and completely lost.

So I would like to ask how the Squeak documentation is supposed
to work.  It seems like one is expected to rely heavily on the
mailing lists.  I have not found that the documentation jumps out
at me so this would seem to be the case.

The Visual Works
documentation jumped out at me and seemed to be pretty good.
Each major addon had its own .pdf file that tells you all about how
to use it.  The problem with this approach is that .pdf files are hard
to make.  The problem with documentation in general is that it is
hard to make and tends to quickly lose its coupling with the source
code.  It seems like wasted effort so programmers don't do it.  No
matter how much their professors and bosses scream/prod at them
to do so.

When I program i use the Class and Method comments as a kind
of running design document that helps me stay on track.  My
comments are much bigger than the actual code.  If I don't do this
I forget what I was doing months or years ago and start doing
something awkward.  I start coding at cross purposes.  My
Method comments come after the Method code and can be as
long as I like.  So you could stick a short comment at the top
and a longer one after the body of the Method.  Lately I have
been commenting each line a lot using
"<---( ... )" comments on hard to follow bits.  This works because
comments are colored green in Dolphin.  It also helps if you can
turn the wordwrap on and off.  I notice that wordwarp is always
on in Squeak.

Another thing that I have been doing for the picoLARC Lisp
Smalltalk Prolog ML
compiler interpreter is to have a sequence of test cases that
serves as a guided tour of how the compiler interpreter works.
picoLARC can be found on sourceforge.net for the community
version of Dolphin Smalltalk.  So far only the Smalltalk Lisp
parts are started there.  A more recent version that includes
a start at a lispy Prolog is not yet uploaded.

I will make it so that each lambda function in picoLARC has to have
a trailing comment after it of 60 words or more or else the
compiler signals a fatal error.

I think that there should be a way of putting Designs into Smalltalk.
That seems to be highly lacking.  The lack of it makes the barrier
for people trying to come into Smalltalk higher.  And it probably
makes Smalltalk coding proceed at a slower less confident pace
than it could.

In 1990 I went to California and was able at one point to talk
with Adele Goldberg in person for 30 minutes or so.  She co
wrote the Smalltalk 80 books.  So my idea for putting Designs
into Smalltalk was to have lists of related methods in things
called FragmentMaps.  Later she came to Boeing and reiterated
what I said as being something that would be good.  But I haven't
seen it yet.  So each Package or Project or Parcel would have a list or
tree of FragmentMaps.  Each FragmentMap would have a
comment about what the methods in it are supposed to be
up to and maybe there might be a HotDrawn diagram that
also shows what is going on.  These methods might be in
different Classes and the fact that they are related probably
is opaque to everybody but the original programmer.  But
putting them in a FragmentMap makes the relationship clear.
At least it points out that there is a relationship.  The lack
of this FragmentMap means that there is a steap learning
curve in front of anyone trying to understand this code.
I'm saying that this learning curve should not be.  And a
simple FragmentMap would get rid of it.  Almost.
FragmentMaps might also have other FragmentMaps in them.

A FragmentMap could also be a way to keep a train of
thought in focus.  So that you could leave it and come
back to it without being afraid that by the time you come
back you will have lost it.  It would be a good way to let
other people know what you are thinking too.

So it would seem that this tendency to not document is
highly dependent on the original programmer(s) sticking
around the mailing lists.  Once they leave then their work
tends to die.  Unless others keep it in their minds.  This
could be why it is common for programmers to think that
rewriting is easier than reading.  That by the time you
figure out how some code works you could have rewritten
it.  I have heard that this happens a lot in corporate C
programming.  It got so bad that Boeing decided that
they mostly no longer want to have any programmers.
Just system analysts and software development tools
that program themselves.  First of all most of the projects
would fail and second of all the ones that didn't fail would
quickly die once the original programmers left. and then
they would have
to be rewritten.  The software development department
was losing so much money and not producing anything
much good so they tried to get rid of it.  But you can't
do that.  Another problem is that they put managers in
charge who know nothing about software.  Bad move.
People who know nothing about software making important
software decissions.  Can you say dissaster?  Would
Microsoft do that?

How can this be a good thing?  How can it be the
accepted practice?  So in corporate they have tried all
sorts of different intense ways to keep software from
rotting.  But none of it really seems to work.  Maybe
something simple like FragmentMaps would help.
Maybe FragmentMaps could solve it.  mostly.
FragmentMaps are simple.  Maybe a simple thing would
work best.  Programmers like the first simplest thing they
can find.  And then they just do that.  From then on.


The problem is:  How are all these methods related?
And how do you communicate that?  The problem is:
That many subsystems can be scattered across
several different Classes.  And the fact that they
are related is completely opaque to everyone but the
original programmer(s).

FragmentMaps would make it a lot easier for new programmers
to get up to speed.  It would also make it a lot easier for
Projects to stay on track and to keep new programmers from
straying a lot from the original design ideas by pure accident.

Protocals in Dolphin perhaps are like FragmentMaps.  But
Protocals are about public interfaces.  If usage comments
could be attatched to Protocals that would be good.  If they
were used.  But FragmentMaps could describe both interface
and implemenation designs.  They would make coding easier
and would make designs more public and easily accessible.

FragmentMaps would be easy to implement too.  It's just
a named list of methods with one or more comments
attatched.  A brief comment.  A details comment.  And
a usage comment.  Even without the comments
FragmentMaps would still be highly useful both for coding
and for communicating.

If you wanted to get fancy you could make it so that
text selections within each Method are displayed which
can drill down into the details.  When you pass over a
text selection a comment comes up in a ballon or
something.  When you click on a selection all the
Methods in it are displayed.  If you wanted to get
fancy but this is not needed.

There could be a tree Pane and a text Pane.  The
tree Pane has a tree of FragmentMaps and Methods
in it.  Each FragmentMap can have other FragmentMaps
or Methods indented under it as its children in the tree
Pane.  Each FragmentMap gets a name.  If you click
on a Method the source code for the Method comes up.
If you click on a FragmentMap the comments for the
FragmentMap come up.  Then you just need Add and
Delete.  Each Project could get a tree of FragmentMaps.
Add could just put up a Prompter where you type in
Class>>method
Class class>>method
If you wanted to get fancy you could add drag and drop.
The Prompter comes up with an example in it:
Class>>method or Class class>>method
How about a Prompter where you can input multiple
Class>>method strings.

FragmentMaps could be labelled [Imp] or [Implementation]
or [Int] or [Interface].  I include the short versions because
I know how you hackers love to make and use conflicting
ambiguous cryptic and contradictory lingo with lots of special
cases.  I suggest a two button Dialog comes up that enforces
the long versions.  All that typing you know.

And that's it.  You don't need more than that.  A Squeak
interface expert aught to be able to implement this in a
day or three.  And a Project expert aught to be able to
add FragmentMaps to Projects in a day or three by just
having the FragmentMap tree binary dumped into the Project
file at first and then later a textual version of the dump that
would last could be added.  Dolphin has a textual way of
doing binary dumps.

FragmentMaps I would like to see are for the interfaces
and implementations related to the >>future Method and all
related Methods in the Croquet and also the routing
and controlling in Croquet.  Both the interface protocals
and the implementation details in FragmentMap form.

Also a sequence of test cases that goes from simple to
complex and demonstrates all the major usages if that
is possible would also help new programmers get up to
speed and serves as an interactive way to show how these
things should be used.  I have seen Demos in Squeak and
that is good.  And Test Classes and that is good but a
lot of the time these Classes are not very full and I am
guessing that there is not really a sequence of test cases
that a newbie could use to find out all the different usages.

I am very methodical when I program.  I single step all the
test cases to make sure they are running the way that I
think they should.  When my stuff works it tends to have
no bugs from then on.  I can't really be very random. I
have to be able to trust things that I have finished.
Because it is hard for me to figure out what is going
wrong if there are lots of bugs coming in from things I
have already finished.  So usually things I finished have
no bugs.  Once they run they run without bugs from
then on.  They can only have missing features.  But
no bugs.

I am mystified by programmers who can take a program
and shoot random fixes at it and somehow make it work.
It seems like most programmers are like that but I am not.
I need to be able to understand everything at once so I
can know that new things are not contradicting old things.
I need FragmentMaps.

In Dolphin Packages can contain loose Methods.  That's
where a method is put into a Class that is owned by a
different Package.  In Squeak Packages seem to be called
Projects.  In most of my Packages it is impossible to go
without loose Methods.  It would seem to me that in Squeak
the only way this could work was if all methods were loose
in Squeak Projects.  In other words no single Project owns
a Class.  Therefore all Projects can stick a method into
any Class.  Is this in fact the case?

So, I would like to propose that something like FragmentMaps
would be a good dynamic way to document Smalltalk Design
in Packages Projects and Parcels.  It would also be easy
for programmers to use since all they have to do is stick
related methods into a tree by dragging and clicking.  It would
be good if programmers could comment what the FragmentMap
was about but even if they didn't the FragmentMaps would still
be good.  FragmentMaps would be an easy way to both aid
in coding by keeping trains in focus and FragmentMaps would
aid in telling others what is going on.  Code reviews would be
a lot easier.  Simple to implement.  Please do it somebody.

If nobody does it then perhaps I could do it as a way of
learning about >>future and routers and controllers.  maybe
then people would tell me what was going on so I could
put it all into a FragmentMap tree(s).

Perhaps FragmentMaps should also be called
AspectMaps.  Maybe Aspect is a better word.
But Fragment has the word Frag in it.  So that is
also good.

-Kjell