Begin forwarded message:

> From: Marcel Weiher <marcel / metaobject.com>
> Date: September 1, 2006 12:11:52 AM GMT+02:00
> To: The general-purpose Squeak developers list <squeak- 
> dev / lists.squeakfoundation.org>
> Subject: Re: Thoughts from an outsider
> Reply-To: The general-purpose Squeak developers list <squeak- 
> dev / lists.squeakfoundation.org>
>
>
> On Aug 30, 2006, at 15:38 , tim Rowledge wrote:
>>>> And dont go down the road that "smalltalk is simple so the
>>>> code documents itself".  The code NEVER documents itself,
>>>> that is a cop-out and a bold face lie.
>>
>> Well I have bit of experience in Smalltalk and I find myself  
>> substantially in agreement with JJ here. Sure, senders and  
>> implementors are fabulous tools to have but they offer nothing to  
>> help understand what is likely to happen with exceptions and very  
>> little for Tweak signals etc.
>
> That is because the code at that point is not "straightforward",  
> that is, it doesn't directly reflect what is going on because it is  
> actually implementing a different architectural style (in some  
> sense a different language) using what is available in OO/Smalltalk.
>
>> No amount of staring at source code will tell you what the author  
>> might have *wanted* the code to do, nor what misbegotten changes  
>> somebody made after misunderstanding the intent of the code at a  
>> later point. Source code tells you what *actually* happens, not  
>> what is *meant* to happen. Anybody that tries to tell you that the  
>> code does exactly what it it supposed to is almost certainly lying.
>
> I have found that a combination of TDD-style unit tests and  
> "intention revealing" programming style works really, really well  
> at documenting what I *meeant* to happen.  Which is kind of funny  
> because it doesn't require any new technology, just technique.
>
> However, it turns out that there are things this combination  
> doesn't cover, and those tend to be the above case of indirectly  
> programming in a different style/language using our current  
> mechanisms.  So it appears to be a good indicator of when you need  
> to start twiddling with the language itself.
>
>>
>> Adele Goldberg expressed it once as "if the code isn't documented,  
>> it doesn't exist" since without reasonable doc there is no way to  
>> count the code as usable in the long term. I tend to add the  
>> corollary clause "and if it doesn't exist, what did we pay you for?"
>
> Funky.  At the last OOPSLA there was a very similar definition of  
> "legacy code":  code that doesn't have tests.  I thought that was  
> really great.  If it doesn't have tests, I can't understand it, and  
> can't evolve it safely.  I would also claim that, despite the fact  
> that I like the fuzziness of natural language, unit tests are  
> better to have than comments, because whereas comments tend to  
> always be out of sync with the actual code, we have a simple way of  
> ensuring that the unit tests and the code do not diverge.
>
>> Another old friend of mine has also coined the rather nice idea of  
>> "program the document, don't document the program"
>
> Essentially very similar to TDD...write the spec/tests/doc, then  
> code it up.  The nice thing about tests is that they can tell you  
> when you're done.
>
> That said, it would be interesting if it is possible and/or useful  
> to integrate these notions, maybe similar to what was done in the  
> PIE system:  first write documents describing fuzzily what you  
> want, the possibly replace/augment with tests.  Only when either  
> one or both are available add code to make it do what the doc/tests  
> say.  I guess you could even have some sort of automatic linkup  
> such that it only makes sense to add code in response to one of  
> these documentation/test nodes.
>
> Marcel
>
>