Re: commenting, was Re: Use of declare blocks

[tmoran@acm.org]

I think we mostly agree.  It's bad to have a machine cluttered with files,
or code, that you think might be useful, but in fact it's so poorly
described that it can't be found, or understood when it is found.  So the
system should force throwing away such things.  If you truly think you
might need it in the future, you should adequately describe it now, before
you've forgotten.

Sometimes you know the code or file you are creating is "for the ages" and
you spend the necessary time thoroughly documenting it.  But often you
don't know for sure, and think the likelihood of future use is low, so
spending a lot of care is a probable waste of time.  Minimal documentation
is then appropriate.  Rather than having two levels - minimal docs/full
docs - and going from level 1 to level 2 when you need the program the
second time, I suggest several levels, with transitions dependent on your
estimate of the likelihood you'll need it again, and the rate of decay of
your memory.

For example, in developing a binding to some API, I do a lot of throw-away
programs to test that I understand the API calls correctly.  I then
document the binding.  But then a few years later, on some newer project,
I recall "I once did a program that did much of what I need now, I wonder
where that old program might be."  I'd like to either know that program is
definitely long gone, don't waste time looking for it, or else have a file
description that lets me easily find it, and internal documentation that
makes it easy to refresh my memory, to help with today's project.