lex at cc.gatech.edu
Wed Mar 1 00:28:03 UTC 2000
Just so long as we actually do end up with comments, instead of just
talking a lot about them. This [CCC] idea is pretty neat.
"Charles-A. Rovira" <crovira at wt.net> wrote:
> I'd just to add a little formalism to the class comments. Managers and other
> anal-retentive types (and I've clenched my own butt on more than one occasion,
> :-) like to see this approach and level of detail. Gives them the "warm and
> fuzzies." Also makes the life easier when some schmucks changes their minds
> and you have to reopen that can of worms.
> Could we give the names* of all
> pool dictionaries (and why we need them)
> globals & what class(es) it should be (or be what type of a collection of),
> class vars & what class(es) it should be (or be what type of a collection
> class instance vars & what class(es) it should be (or be what type of a
> collection of),
> instance vars & what class(es) it should be (or be what type of a collection
> Carrying this down into method comments describing
> parameters & what class(es) it should be (or be what type of a collection
> of), and
> answered objects & what class(es) it should be (or be what type of a
> collection of),
> really eliminates a lot of guessing when something was not of the class you
> were expecting. (Its usually because you didn't know what to expect and gessed
> It would also be good to give
> the "raison d'etre" of the class (and some reason for the design, no matter
> how cryptic,)
> some examples of initialization, use and destruction.
> That's in addition to the excellent comments supplied so far.
> *without getting into semiotics and other linguistic faolderol, having
> variables names that don't just give their class (since that is provided in
> the class comment) means that instead of seeing variables named "aCollection"
> one can see variables named "invoiceLineItems" or "keyboardSemaphores" or
> "braSize" (which could be a number of centimeters in the metric system or "cup
> selection" in the British system, and would then be described as
> braSize -> nil or Array of:
> (one of 'm' 'b') and
> (Integer (range 58..105) or
> String (one of 'a' 'b' 'c' 'd' 'e' 'wow') ).
> And don't get me started on pants measurements: waists, in-seams, cuffs,
> zipper etc. Oych!)
> If you rather use an XML description, go heads, knock yourselves out.
More information about the Squeak-dev