Thoughts from an outsider
J J
azreal1977 at hotmail.com
Sat Sep 2 10:00:52 UTC 2006
Thanks Tim. I think the heat here is because if my comments are taken
personally it looks
like I am calling volunteers lazy. That is not the case. Someone is lazy
when they are
not willing to do what they are responsible for (i.e. what they are paid to
do or what
the life/happiness of people they are responsible for depend on them to do).
If someone
doesn't want to document code that they wrote and gave away for free, that
doesn't
make them lazy or negative in any way.
But the documentation needs to get done. So if the author doesn't want to
thats ok, it's not
bad. But we can start a documentation project, get people who do want to do
it and
get this done. But the worst thing is when people trying to do this project
don't get the
help they need because everyone thinks it isn't necassary because "the code
documents
itself".
>From: tim Rowledge <tim at rowledge.org>
>Reply-To: The general-purpose Squeak developers
>list<squeak-dev at lists.squeakfoundation.org>
>To: The general-purpose Squeak developers
>list<squeak-dev at lists.squeakfoundation.org>
>Subject: Re: Thoughts from an outsider
>Date: Wed, 30 Aug 2006 15:38:40 -0700
>
>
>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
|