Jason Johnson wrote:
> It truly is annoying when you look at classes with no comments.
> Writers of classes need to remember that the next person looking at
> the code doesn't have the whole architecture in their head like you do
> so they may not know where to start.
> 
> But "every method should" is an exaggeration, no?  I mean do you want
> a comment for every accessors saying "this is an accessors"?

No, it should say what the variable is good for. We had this discussion 
here recently and I have to admit that there is something to be said for 
putting variable comments into the accessors instead of the class 
comment (where they are much harder to find and to update). In an 
optimal solution these would be automatically synchronized so the 
comment of the accessors would be  the comments of the variable and vice 
versa. Here is a good example from our code base:

cacheLocally
	"Boolean - if true, tells the system to maintain a locally cached copy 
of the document file."
	^ cacheLocally

Cheers,
   - Andreas

> 
> In any event, Squeak could certainly use more commenting.
> 
> On 9/12/07, Andreas Raab <andreas.raab at gmx.de> wrote:
>> Steven W Riggins wrote:
>>> 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.
>> Amen, brother.
>>
>> Cheers,
>>    - Andreas
>>
>>
> 
>