Well, this brings up a good point.  After using Smalltalk for a while
I actually *do* feel that the language is somewhat "self documenting"
(i.e. it reads often like english).  But there are 2 places that the
code can't help with documentation; (1) why did you do this? and (2)
why did you change it from what you had before?

In the first case nothing can help but a comment.  In the second case
the tools, e.g. ChangeSet can show us *what* was done before, but I
think we need a way to add comments to change sets to explain *why* it
was changed at all.  Without this, people will look at the old version
and say "hrm, why did this guy change it?  The older version looks
obviously better" and off they go to relive old mistakes.  Or maybe
something has changed and the old way should be used again, but you
can't know without some kind of comment.

On 9/12/07, tim Rowledge <tim at rowledge.org> wrote:
>
> > But "every method should" is an exaggeration, no?  I mean do you want
> > a comment for every accessors saying "this is an accessors"?
> Actually in general I *do* want a comment in accessors; not a simple
> minded one though. Y'see I don't *like* simple accessors. Instance
> variables are there for a reason and they're not publicly accessible
> for another reason.A method that opens up my object to rape and
> pillage damn well *should* be commented. A class where all the
> instvars have accessors is generally going to be horribly abused. I
> mean, what is this ? C++? Gimme a break. People will be trying to
> tell me that Squeak must have an "access path notation for variable
> members" next. If I'm supposed to be exposing my programmatic
> buttocks to the world I want a  comment to explain why!
>
>
> tim
> --
> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
> Strange OpCodes: CSF: Charge to NSF
>
>
>
>