Comment with parsimony

[Alain Farmer]

Hello Chipp,

> I sometimes code functions which are called from
> all over the place, and usually I try and put a 
> comment inside the function regarding where it's
> being called from...

Extreme Programming (XP) does not favour documentation
either, but Allistair Cockburn (guru) criticizes XP
for this in his book "Agile Development
Methodologies". My take on it is that a small tech
manual should document the system (including the
dependencies you mentionned). I am not as "extreme" as
I could be [yet].

> just in case I change it later,
> I want to know what the possible 'impact' is.

The XP solution is their *tests*. A test is programmed
to test each segment of code once it is programmed
and, thereafter, every time any change is made to the
system. You make a change, you run all of the
automatic tests, and they will immediately reveal if
you have broken something. You don't have to wonder
about it, discover it later, predict everything that
could happen, worry about it, etc.

> Currently it's difficult for me to find
> all 'referring' handlers to a function
> (any ideas anyone?)

A script-searching algorithm that searches all of the
scripts of the stack(s) looking for the names of the
dependent handlers. Very simple to do. There are many
such stacks in the HyperCard Pantechnicon. As you
know, you can convert these HyperCard stacks to MC or
RR by opening them with MC or RR.

  http://pan.uqam.ca/cgi-bin/usemod/wiki.pl

BTW, these same stacks could also be used extract all
of the caracteristics of your stack(s), and thereby
provide what you need to document your stack once it's
completed instead of before-during-and-after. Not the
"why" but at least you get the "what" and the "how".
The goal, you see, is to document without the hassles
of documenting!

Interesting?

Alain Farmer

__________________________________
Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo.
http://search.yahoo.com