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