From: Dave Fayram <dfayram@...>
Date: 2005-04-28T06:19:29+09:00
Subject: Re: Comments Are More Important Than Code

> If I have to debug some legacy code, it is because it
> doesn't work: either because it is in error for the
> current parameters or the requirements have changed.
> It saves a lot of time if the intent of the function is there
> with the code.

If you've got requirements that extend to that level of the software,
I'd highly recommend that you get the code into a unit test framework
and devise an automated test for each requiremnet. I consider Legacy
Code as, "Any code without a reasonable unit test suite."

Tests will clarify these issues far more than any documentation ever
will. Having worked as a government contractor, I can tell you with
great conviction that a pound of paperwork won't really help anyone
with a big mess of bad code. Likewise, producing that paperwork doesn't
really help the process of writing code in the first place.

> Good comments about the intent of functions and algorithms
> save time and lessen frustration.

I suspect that we're having a debate of defintion. When I think good
documentation, I think of what Rails does. That's what I'm trying,
perhaps unclearly, to express.