Where to put change descriptions (Was: need help learning Ada for a modula-2 programmer)

[Jacob Sparre Andersen <jacob@jacob-sparre.dk>]

Nasser M. Abbasi wrote:
> Dirk Heinrichs wrote:
>> agent@drrob1.com wrote:

>>> --  REVISION HISTORY

>> You should avoid putting the revision history _into_ your files. It's
>> the job of your version control system to handle this. Putting it
>> into the file increases the probability of getting merge conflicts.

> Revision history belongs to the source code itself. If you remove it
> and put it in some separate container such as a database, then you are
> stuck to having that database along side for ever, and it means no one
> can see the revisions made to the source code, unless they access and
> install some additional software and files.

It looks like we've found a case of two rather different schools of
thought.  (Luckily we agree that it is good to document changes. ;-)

Once upon a time I kept revision histories in my source files, but the
way I did it (which looked rather a lot like <agent@drrob1.com>s
example), it didn't really add any value.

One reason that revision histories in source files don't make sense to
me is that I often make changes which impact more than one source file.
Which source file should I put that change description in?  Should I
update it in parallel in all the source files I change as I work on the
change?

I agree that one should document the changes in a change (commit) as
early as possible.  I usually do that by writing an issue describing
what I think I have to do and why I think I have to do it.  Once the
issue is written, I start on the change.  More or less in the order;
interface, tests, body (and finally; figuring out what went wrong).

As I already have documented beforehand where and why I want to go, it
is seldom hard to write a meaningful description of the change once I
have verified that it passes both regression tests and new tests.

Greetings,

Jacob
-- 
»But you have to be a bit wary of a ship that collects
 snowflakes.«                                  -- Diziet Sma