Class comments!?

Alejandro F. Reimondo aleReimondo at smalltalking.net
Sun Oct 17 18:55:25 UTC 2004



>For the method comments the non trivial should have

> a comment talking what does the method.

Please instead of comment methods, please consider

the possibility to comment messages.

aMessage has, aSelector, aCollection of arguments...

AND a Comment specifying it's semantics (not a

method's semantics).

Each time aClass implement a Message must HAVE the

SAME "Comment" included in the method implementation.

Methods (in my opinion) do not need to be commented

because must be simple, and refactoring efforts must be

put if a method has a complex resolution.

What we call "comments" in Smalltalk is message comments.

Code comments are not required if you work with objects...

(no "Code" class in the ambient)

Comments for classes? Why?

Classes are atomic, abstraction of one object.

The real interesting things to comment/use are machines

or frameworks (abstraction of a machine).

For introducing framework, text are not very useful

as time (exposure of the person to instances of it).

The information process require a work to be realized

to instantiate expertise in a domain, so it is NOT a great

objective to reduce time of exposition of a person to a domain

trying to understand how to instantiate successfully a framework

to solve a concrete problem.

best,

Ale.


----- Original Message ----- 
From: "stéphane ducasse" <ducasse at iam.unibe.ch>
To: "The general-purpose Squeak developers list"
<squeak-dev at lists.squeakfoundation.org>
Sent: Sunday, October 17, 2004 9:40 AM
Subject: Re: Class comments!?


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
>
>





More information about the Squeak-dev mailing list