Re: Writing changelog entries

["Randy Brukardt" <randy@rrsoftware.com>]

"Brian May" <bam@snoopy.apana.org.au> wrote in message
news:sa48y74n7bq.fsf@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.

The code should be commented as to why it is the way currently is. Of
course, that isn't always done (when it appears obvious). But if a bug
report causes a change, usually I'll include the bug report number and an
explanation of why the code needs to be the way it is.

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

Well, unless I've lost the ability to read comments, that's not likely to be
an issue. Moreover, I would be remiss if I don't use the bug report number
to look up the associated regression test to insure that I didn't
reintroduce a bug.

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

Couldn't happen: even if I didn't manually check for a regression, the
regression tests (which are run very often - usually immediately after a
change) would have caught the problem. For this to happen, I've have to have
failed to comment the code *and* failed to create a regression test. I'd
fire myself if I did that!

> ...repeat...
>
> See a pattern here?

Sure; some people neither create tests nor properly comment their code. What
good would a changelog do? It's widely separated from the code in question;
I don't want to have to look in a half dozen places to understand some code!
And if people aren't putting in useful comments or creating tests, why would
they write a useful changelog?? (Certainly, if I didn't do the first two
because I was in too much of hurry, the third will be even more useless...)

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

Absolutely. At the place of the bug, in the code where you can't help but
see it the next time your debugging path leads you there.

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

Those would be pretty useless comments. The only comments that *are* useful
are those that explain *why* code is the way it is. The other questions
(what, where) usually can be answered by reading the code itself.

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

I don't see why; it's widely separated from the code in question. There is
no sane way to associate the descriptions with the code -- and that's what
you need to understand the code and avoid reintroducing problems.

I don't believe in separate design documents (other than for "big picture"
sorts of descriptions), either.

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

We always tried to keep the systems maintained in parallel. Traditional
source code control systems do a lousy job of this, and we wrote our own
tools to manage the files (most of them are shared between the versions,
only a few need manual upgrades).

But I realize that won't work everywhere.

> Not to mention security related issues. A good changelog may help
> identify what versions of the software had a serious security bug for
> instance.

That seems like a job for a bug tracking database. We've never computerized
that (I still use the paper-based system we worked out in the 80s), but it
would be easy enough to do.

I don't want to claim that the changelog has no use whatsoever, but I don't
think there is much point to getting fancy with it. There are better places
for virtually all of the information that could be in it; you just need
enough to insure that you can find a particular change in the rare case that
you need to see how you got to the current code.

                            Randy.