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