[CCC] a few comments on the comments on my comments...

Dwight Hughes dwighth at ipa.net
Wed Mar 1 05:28:53 UTC 2000


In general, I would prefer that class comments be reasonably self
contained -- so I don't have a problem with the minor redundancy of the
True/False comments -- especially since the comments are so short. Also,
True and False have the unusual property (in the class hierarchy anyway)
of truly being mirror images of each other -- so the repetition is
particularly apparent. If the common section was more extensive, then I
would want to move it to their superclass and add links to it instead.

One thing I'm trying to be mindful of as I compose a comment is to try
to give enough detail to prevent some of the various "newbie" problems
and misunderstandings that I've seen come up -- and to try to document
some of the "gotchas" in general.

I am actually not too crazy about having a class comment explicitly
mention subclasses of that class (like I did in Boolean) -- but for the
core classes like these, it is very important to document their
interrelations and structure (which change only rarely), so I think
certain exceptions can be made.

I would definitely agree that the variables defined for a class should
be documented by their purpose in the class -- just documenting the
class of object they usually contain is of little value. Without the
added meaning, we might as well leave them out of the comment.

Now, concerning thoughts about what all we could/should/might
potentially turn the comments and their general support and examination
structure into -- I would like to ask that we *please* try to stay
focused on creating the fundamental class comments for a reasonably
comprehensive set of classes for now. Believe me, I would like to see
things go far beyond what they are now (and I have a number of ideas of
what and how), but all of that is just smoke and noise until we create
the core documentation to begin with.

-- Dwight





More information about the Squeak-dev mailing list