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
|