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