Comments describe the code as it currently exists, commit messages describe the evolution of the code. This is a very important distinction. 1. If one needs to

Comments describe the code as it currently exists, commit messages describe the evolution of the code. This is a very important distinction. 1. If one needs to understand the history of the code to understand the code in its current state, the code is bad. 2. But if one is one is already familiar with the old code, it is easier to leverage that to understand the new code than start from scratch. So we write commit messages for 2, but per 1 we can't have those commit messages be the only way to understand it, nor can we have the code comments refer to the old versions of the code that are removed[1]. [1]: except for the vaguest "other xxx you might think of were tried and didn't work".