[DOCS] Re: Documentation [was: Morphic tutorial]

Stephane Ducasse ducasse at iam.unibe.ch
Thu Feb 13 10:41:20 UTC 2003


> Hannes,
>
> I think you're missing the point of Stephane's message. He was 
> pointing to
> "code based" documentation which I interpret as a documentation of the
> implementation rather than the architecture.

Yes


> Architectural issues (like how
> things "should" be - notice the use of phrases like "typically" or "by
> default" in the little blurb I wrote) cannot be covered by unit tests 
> very
> well.

Indeed this could be a pain.

> Similarly to "usage information" (e.g., how-to) since tests typically
> have the wrong "usage density" (e.g., there should be tests for all the
> #addMorph: variants none of which tells you that "the way to go" is to 
> use
> #addMorph: - tests actually can be confusing for this kind of 
> information).
> I'm sure Stephane is well aware of this.

I see what you mean (nearly)
For me test should tell some small scenario in terms of the object 
interfaces
as you want to have a low speed change for tests.

Of course when there is a vicious point having a simple test is always 
cool to catch it after.

(What frustrating medium we used to communicate. Teleportation we need 
you.)

Here are some of example of tests I would like:
-> if you open this socket then if this is not connected you get this 
error.
-> if you add a button in a window, changes the color of the button 
does not work
as the window takes care of the look.
-> if you add a button into a frame, then add this frame into a window, 
  changes the color of the button does work!!!

So this is not really complex and tell me a small story.

The stuff we are used to do in the method comments is a potential SUnit 
test . In fact Smalltalkers has been spoiled and sometimes are blind to 
see the advantages of having repeatable
tests.


Just a fun and true story. Alex wrote during the last two months an 
implementation
of a module system for smalltalk. He wrote all kind of tests that 
capture the semantics we wanted. Then we discussed with steven and 
realized that his implementation was cooler. Alex reimplemented the 
core model in one afternoon and told me: "this is fascinating because 
all the tests run so the model should work. amazing." and it was 
working.

That's the power of tests. Specifying behavior. After this is clear 
that you have to take care
about the granularity you want to have.


>
> Cheers,
>   - Andreas
>
>> -----Original Message-----
>> From: squeak-dev-bounces at lists.squeakfoundation.org
>> [mailto:squeak-dev-bounces at lists.squeakfoundation.org] On
>> Behalf Of Hannes Hirzel
>> Sent: Thursday, February 13, 2003 10:24 AM
>> To: The general-purpose Squeak developers list
>> Cc: The general-purpose Squeak developers list
>> Subject: [DOCS] Re: Documentation [was: Morphic tutorial]
>>
>>
>>
>> Hi Stephane
>>
>> Stephane Ducasse <ducasse at iam.unibe.ch> wrote:
>>> May be I should insist and say again that all effort of
>> documentation
>>> (code based) out of the image are doomed and that Unit
>> tests are the
>>> only way to go.
>>
>> Definitly no!
>>
>> See Ralph Johnson's thoughts on documentation
>> of June 1999 http://minnow.cc.gatech.edu/squeak/736
>>
>> We need for example a good explanation about MorphicEvent handling
>> as outlined by Andreas Raab in another thread.
>>
>> Having a tutorial about using ProtoMorph for learning about Smalltalk
>> reflection and learning about the Morph hierarchy is helpful as well.
>>
>>
>>> Not sexy fancy supercool but the only way to get concrete scenario
>>> of the system
>>> in a reproduceable way and in sync with the system because
>> even example
>>> methods got obsolete.
>>
>> I agree that we need more unit tests as they provide an automatic
>> mechanism
>> to find out about inconsistences!
>>
>> Regards
>> Hannes
>>
>
>
>
Prof. Dr. Stéphane DUCASSE (ducasse at iam.unibe.ch) 
http://www.iam.unibe.ch/~ducasse/
  "if you knew today was your last day on earth, what would you do
  different? ... especially if, by doing something different, today
  might not be your last day on earth" Calvin&Hobbes




More information about the Squeak-dev mailing list