Thoughts from an outsider
tim Rowledge
tim at rowledge.org
Wed Aug 30 22:38:40 UTC 2006
On 30-Aug-06, at 1:34 PM, Ramon Leon wrote:
>> Communities that tell their users to RTFM find themselves
>> alone very quickly. We're telling ours to RTFSC. There has
>> got to be a compromise better than that.
>>
>> --Benjamin
>
> I never said documentation was bad, I was simply responding to the
> invalid
> accusation that the Smalltalk style of self documenting code is
> wrong, or
> that we're copping out or lying made by JJ below...
>
>> 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. 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.
Comments in methods ought to offer some help in decoding the
expectations for the method as a whole, or for parts of the method.
Class comments ought to offer a somewhat higher level view of what
the class is supposed to do and the limitations it is known to have.
Other forms of comments and documentation are needed to give later
authors some hope of being able to use, maintain and improve the
system. You need tutorial type documentation to offer newcomers to a
part of the system a chance of getting some sense of the system
before they can even begin to understand the actual code.
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?"
Another old friend of mine has also coined the rather nice idea of
"program the document, don't document the program" to cover a concept
of merging doc and code in the tools so that you can write spec,
explanation, commentary, examples and limitations mixed in with
executable code. It's not hugely different to some aspects of the
late Jef Raskin's idea of The Humane Interface (see http://
www.raskincenter.org) and it wouldn't be too awful implemented as a
nice document editor that has a style for 'source code' that actually
means source code rather than just using a fixed pitch font. Hmm, now
where might we find a document editor with intimate associations with
a compiler?
tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
A)bort, R)etry or S)elf-destruct?
More information about the Squeak-dev
mailing list
|