Comment with parsimony (was something else)

[Shari]

>Firstly I should state that if you need to know where you call a function
>from it's poor design.

I don't agree.

If you want to rewrite sections of code, you need to know how that 
may impact other sections of code.  I comment liberally now.  I 
didn't used to.  What seems obvious during creation, is not always as 
obvious six months later when you want to go back in and 
change/update/add/fix something.

Sometimes I want to rewrite a section of code, and *add* the called 
handler into the calling handler, unseparating them.  For this, I 
need to be absolutely sure that no other handler calls the second 
handler.  And if you have 200 handlers, you aren't going to remember 
what calls what six months after you wrote the code.

Or maybe you want to delete the function.  Or change it.  In changing 
it, you better know exactly who is going to use the result.

I try to give handlers a very obvious name.  In Blackjack Gold, I 
have handlers called dealCards, dealOne, splitMe.  So at least I know 
what they are designed to do.  But even with that, there are 
handlers, such as my hideCards handler, that gets called at the end 
of the hand, but ALSO gets called at other times,  which I could not 
tell you when those times are any more.

It started out being the handler that ended a hand, removing the 
cards left on the table.  But it turned into a catch all for every 
object that could become visible during a game, every graphic, every 
button.

I made the game self-repairing, so that if the user hits 
Command-Period and stops it in midstream, handlers that get cancelled 
don't ball up the game leaving things visible that shouldn't be.  So 
hideCards comes in, and pretty much resets everything to start a new 
hand.  Hides everything that could possibly still be visible, even 
things that in normal gameplay shouldn't ever still be visible.  It 
just *assumes* the worst and handles it.  And zeros out globals, and 
so forth.

So the handler gets called from unexpected sources.  And I honestly 
do not remember all the places I added it in, to be called.

Shari C

-- 
--Shareware Games for the Mac--
http://www.gypsyware.com