4 ms·

> So commit messages to me are almost as important as the code change itself. Why commit messages rather than code comments?

yonixw 6y ago
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.
- oleks 6y ago
  Similarly, comments can lie, but a commit-history cannot. That is, if the commits are digitally signed. Then you know something about who made the change when, and get a hint at why. This is much more valuable than code comments.
hasmolo 6y ago
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.
- pengaru 6y ago
  > 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. That's simply not true, not in a git world where rebasing to rewrite history is standard practice.
  - urxvtcd 6y ago
    The branches you rebase most of the time are your own topic branches, where you know what's going on. And they should be relatively short-lived.
  - ulrikrasmussen 6y ago
    In that case rebasing rather than merging would be the wrong choice, since you're actively obfuscating the history.
  - Groxx 6y ago
    I don't see how this can possibly be relevant to how relevant a commit message is.
antongribok 6y ago
Because code (along with comments) can go away, but commit history will stay.
rwmj 6y ago
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.
peterwwillis 6y ago
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.
daveFNbuck 6y ago
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.
riku_iki 6y ago
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.
dharmab 6y ago
Commit messages can include context outside of the code that would normally be buried and verbose in a comment.
Ericson2314 6y ago
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".
ewindal 6y ago
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.
u801e 6y ago
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.
gilbetron 6y ago
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.

yonixw 6y ago

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.

oleks 6y ago
Similarly, comments can lie, but a commit-history cannot. That is, if the commits are digitally signed. Then you know something about who made the change when, and get a hint at why. This is much more valuable than code comments.

hasmolo 6y ago

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.

pengaru 6y ago
> 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. That's simply not true, not in a git world where rebasing to rewrite history is standard practice.
- urxvtcd 6y ago
  The branches you rebase most of the time are your own topic branches, where you know what's going on. And they should be relatively short-lived.
- ulrikrasmussen 6y ago
  In that case rebasing rather than merging would be the wrong choice, since you're actively obfuscating the history.
- Groxx 6y ago
  I don't see how this can possibly be relevant to how relevant a commit message is.

antongribok 6y ago

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

rwmj 6y ago

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.

peterwwillis 6y ago

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.

daveFNbuck 6y ago

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.

riku_iki 6y ago

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.

dharmab 6y ago

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

Ericson2314 6y ago

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

ewindal 6y ago

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.

u801e 6y ago

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.

gilbetron 6y ago

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.