[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
|