[Pharo-project] What is a well documented class?

Michael Forster mike at sharedlogic.ca
Sun Apr 24 15:12:35 CEST 2011


On Sun, Apr 24, 2011 at 4:03 AM, Stéphane Ducasse
<stephane.ducasse at inria.fr> wrote:
> for the class comment I would have
>
> intention
>        I'm doing that
> collaborations
>        with the help of this class and that class
> main api
>        my main public API is ...
>
>        my subclasses may want to override such specific hooks ...

Yes, yes!  I would like to see those suggestions used by the default
comment template for new classes.


> Implementation notes
>        iv and their purposes

May I ask, what if we stopped ever mentioning instance vars in the
class comment?  Perhaps it's a problem of having only one place to
document both external and internal details of the class, but it
really irks me when the comment template for a newly created class
suggests that I divulge the implementation details in what appears to
be a document of the interface.  Moreover, the comment must change
when the implementation changes, even if the interface remains the
same.  Perhaps that's why so many class comments seem out of sync with
the current state of their classes.

Thoughts?

Mike



More information about the Pharo-project mailing list