Thoughts from an outsider
Marcel Weiher
marcel at metaobject.com
Thu Aug 31 22:11:52 UTC 2006
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
|