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