Re: Writing changelog entries

[Stephen Leake <stephen_leake@acm.org>]

Brian May <bam@snoopy.apana.org.au> writes:

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

If you document why the code is the way it is, _and_ why it is not
some other way that you considered, you can terminate the perpetual
changes. 

Such documentation belongs in the code as comments if it is short
enough, or in a separate design document, with a reference in the
code. 

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

Change logs are not design documents.

-- 
-- Stephe