Comment with parsimony

[Monte Goulding]

> 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?

Very. Ever seen javadoc in action. It generates HTML documentation (One page
per object) based on a combination of comments, dependancies, uses etc.

Cheers

Monte