I've seen that useful commit message make it incredibly easy to see where the code came from and is going. It also never gets 'out of sync' like code comments tend to, as it's a comment on a static place in the code, not a dynamic one.

When bisecting to find the cause of a bug it's usually important to me to understand why a change was made. That's sometimes hard to describe in a comment (especially if you're removing lines). The commit message should tell me the why of the change, and link to background information like email threads and the bug tracker. That's the why of the change, the why of the code itself can go in a comment.

A commit message can give you a better understanding of why a line of code is the way it is. It's like a mini README for your commit.

Suppose you're making a change that has a few paragraphs of commit message explaining what you're doing and why. As well as a large well-commented change in a primary file, you've made some small incidental changes to other files. You're not going to include comments with all the context and explanation on each of these small changes.

If I'm looking at one of the files you incidentally touched later and don't understand why your change is there, I can check the git blame and have a good understanding of why the code looks like that now.

Code comments should explain why a particular piece of code is doing what it's doing right now, and what the expected behavior should be right now. Code should be written so that comments are not necessary at all, but sometimes it's unavoidable.

Now, why a particular piece of code came to be, why the code should have this expected behavior, why something is being added or removed or changed, may be unrelated (or unnecessary) to what this particular code is doing.

So there's two kinds of documentation here: 1) "this is what this code does", 2) "here are the series of events that led to this code". You need the former when you are editing code. You need the latter when you are reviewing code for merge, as well as in the future to figure out how the f*!$ this code came to be (which is useful to avoid re-running into a bug, troubleshooting/understanding a legacy system, or removing important code). The latter may also immediately become obsolete the second time the same block of code is edited, so we keep this historic information in e-mail or code commit messages.

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

Because code (along with comments) can go away, but commit history will stay.

The goal isn't to describe code intent with a bare minimum. It is good to describe in the comment, the code, the readme, and the commit message, all at the same time for complex weird stuff. The goal is to make sure the Future Person can understand why you did what you did.

Commit messages cover the entirety of the change, and only exist in the context of the commit it is attached to. A comment is without exception outdated by the next commit, unless it is rewritten for that commit.

Code changes can be spread over multiple files, with comments explaining local logic only, and commit message provides overall background about the goal of this change.

A commit message will always be associated with a line of code until that line changes. A code comment may or may not be updated when the code changes.

I guess "Code can't lie, comments can". At least the commit comment stick to the affected code and can't be moved that easily.

Commit messages can include context outside of the code that would normally be buried and verbose in a comment.