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@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.