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@rowledge.org; http://www.rowledge.org/tim A)bort, R)etry or S)elf-destruct?