What we could do is really make a push at making sure classes have all 
a clever comment:
I can help.
For the method comments the non trivial should have a comment talking 
what does the method.

Following the pattern:
	Main responsibilities:
	Main collaborations:
	Main methods (4 or 5 max)
	Explanation about internal representation
Example

Main responsibilities:
	I'm a berzerk machine, my main goal is to berzerkify all the clients. 
I'm a concrete class.

Main collaborations:
	For that purpose I use a BerzerkVisitor (whose role is to walk over 
the clients),
	a BerzerkPolicy (whose role is to represent how the clients are 
berzerkified), and the BerzerkNotifier (that is used to notify
	when clients have problems). The clients should reply to BerzerkClient 
interface (acceptBerzerk)

Main Method:
	berzerk:with:
	deberzerk:
	berzerkPolicy:
	
Internal Representation
	visitor is an instance of BerzerkVisitor
	clients is an orderedCollection of accepting berzerk client

On 17 oct. 04, at 02:45, Yoshiki Ohshima wrote:

>   Göran,
>
>> I mean, sure, some of these can have short comments - but is it just 
>> me
>> getting ANNOYED when there is NO COMMENT AT ALL?!
>
>   I am, too (regarding clas comments, but not method comments for most
> of the case).  What should I do?
>
> -- Yoshiki
>
>