Re: Writing changelog entries

[Brian May <bam@snoopy.apana.org.au>]

>>>>> "Randy" == Randy Brukardt <randy@rrsoftware.com> writes:

    Randy> That leaves the rare cases where a problem shows up much
    Randy> later. In those cases, it's usually necessary to debug the
    Randy> entire thing again anyway. So, leaving comments in the
    Randy> place where the code is the most valuable, because it's
    Randy> where you're going to be looking anyway.

Then you come to a line of code that is causing problems.

You can't remember why the line was in its current form (probably a
mistake, and you change it to what looks correct.

Months later you observe a different problem. You change the same line
of code back to the original value, because you can't remember why you
changed it before, and it looked totally wrong before.

Months later you observe the original problem again. After hours of
debugging, you end up changing the same line of code back to the
modified value, because you can't remember why you changed it before,
and it looked totally wrong before.

...repeat...

See a pattern here?

Meanwhile, the real bug is not getting fixed.

You should be documenting *why* changes are made so you don't have to
reinvent the wheel every time you encounter the same problem again.

Comments in the code only really describe what the code does (or more
precisely: what it is meant to do), not why a change was made. Yes,
you could document a complete history of why you made every change as
comments in the source code, a changelog file would appear to be
better suited for the purpose though.

Also, a good changelog is required if you want to upgrade numerous
systems, and want some idea of what is likely to break in the upgrade.

Not to mention security related issues. A good changelog may help
identify what versions of the software had a serious security bug for
instance.
-- 
Brian May <bam@snoopy.apana.org.au>