Thoughts from an outsider

J J azreal1977 at hotmail.com
Sat Sep 2 11:06:42 UTC 2006


I understand what you're saying, but tests still don't remove the need for 
documentation.
When I did the pier/seaside install I ran the tester for fun.  Something 
failed.  Without
documentation how do I tell if the code is broken or the test is old?  
Something is obviously
wrong, but what?  The test tells me what someone wanted at one time, but 
either they
don't want it anymore or someone broke some code, or maybe I really did 
catch a problem.

And I don't see this about "code is never in sync with documentation".  Why? 
  You know
when you change code right?  So let someone know so they can update the doc. 
  And
sure if your documentation is specific like "we chose to loop through the 
collection" then
that could be a problem because low level implimentation details change the 
most.

But "writeAllObjectsToFile" is always going to basically do the same thing 
as long as it
exists.


>From: Marcel Weiher <marcel at metaobject.com>
>Reply-To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>Subject: Re: Thoughts from an outsider
>Date: Thu, 31 Aug 2006 15:11:52 -0700
>
>
>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
>
>





More information about the Squeak-dev mailing list