Comments (was: Re: OrderedCollection new allButLast?)
Steven W Riggins
mailinglists at geeksrus.com
Wed Sep 12 02:16:15 UTC 2007
On Sep 11, 2007, at 6:13 PM, Andreas Raab wrote:
> Steven W Riggins wrote:
>> The class documentation should say what the intention of the class
>> is.
>> "THIS CLASS HAS NO COMMENT!"
>> Hmm, lets look at the method. Nope, no comment their either.
>> Shrug, who knows what it's supposed to do? :P
>> (Pet peeve of mine working with Squeak for awhile now <g>)
>
> I'm sure you'll enjoy this little rant then:
>
> http://lists.squeakfoundation.org/pipermail/seaside/2007-March/
> 011443.html
>
> Cheers,
> - Andreas
>
>
Heh, my code is not much better, but that does not mean I can't work
for improvement.
I think what I've noticed, being an "outsider" these last few years
(outside of the smalltalk community) is that there appears to be this
mentality that because the methods are short, they are self
defining. "See the code"
The problem I have run into is that code defines what the method
does, not what the method was intended to do.
Then I am left being a spaghetti programmer, not much unlike my BASIC
days of 1985, to unwind code paths and try to figure out how a method
is being *used* to see if the method is doing what the callers
*think* the method should be doing.
So what has happened is:
* Spend 6 hours figuring a method out, what it does, etc
* Talk to the engineer about it saying "it does this"
* "Oh damn, it should not be doing that, it should do this other thing"
* Fix the method in 5 minutes or less.
This is not worse than my objective-c Cocoa projects, mind you,
finding Apple docs is better these days with the built in tools, but
because the squeak browser makes it so easy to see class comments,
and see a individual method's source, having a short 1 or 2 line
comment about *intention* would just be fantastic.
This is similar to using s-units to develop code (hi john) which we
on the Sophie team have been awful at (hi john), but the concept as
you know is to define what the method should do, then implement the
test, then implement the method.
Likewise, I feel every method should start with a comment, and this
nonsense about the method selector being good enough to define
intention just tossed out of the equation. Show me a party where you
can pass 1-4 words between 15 people and get the same 1-4 words at
the end. :) However, several sentences can be better, or not
depending on the engineer, but at least it is a start.
Thus, I would ask that if this is not being done now, I'd ask people
to evaluate this concept and look at their code from another
developer's eyes, and hopefully understand that a statement of
intention should be the first 'code' written for any method.
Steve
More information about the Squeak-dev
mailing list
|