Re: Rant about ChangeLog entries and commit messages

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

> I didn't say you cannot or should not use these tools.  But a good comment 
> on a piece of code sure beats a good commit message, which must be looked at 
> separately, and can be fragmented over multiple commits, etc.

I don't see one as "beating" the other because they have very different
purposes.  Sometimes you need one and sometimes you need the other.

The purpose of COMMENTS is to help somebody understand the code as it
stands at some point in time.  In most cases, that means saying WHAT the
code does and WHY (at some level) it does what it does.  Once in a while,
it also means saying why it DOESN'T do something, for example, if it might
appear that there's a simpler way of doing what the code is doing now but
it doesn't work for some subtle reason.  But it's NOT appropriate to put
into comments the historical remark that this code used to have a typo
which caused a miscompilation at some specific place.  However, the commit
log IS the place for that sort of note.

My view is that, in general, the comments are usually the most appropriate
place to put information about how the code currently works and the commit
log is generally the best place for information that contrasts how the code
currently works with how it used to work and provides the motivation for
making the change.  But there are exceptions to both of those generalizations.