[CCC]s

Lex Spoon 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.

Lex


"Charles-A. Rovira" <crovira at wt.net> wrote:
> Hello,
> 
> 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
> of),
>  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
> of)
> 
> 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
> wrong.)
> 
> 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.
> 
> -Charles-A.
> 
> *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 mailing list