3 ms·

> A lot of times, code comments may not be updated along with code changes, so they may not be accurate. A commit message is associated with a change at the tim

> A lot of times, code comments may not be updated along with code changes, so they may not be accurate. A commit message is associated with a change at the time it was made. Code review ought to catch comments that haven't been updated. Further, if a change would have caused the comment to become stale and irrelevant to the project's current state, the commit message would have the same problem. Where you keep it doesn't impact that. If you want to look at historical states, the comment itself is saved perfectly in the old commit, just like the commit message would be. > The git blame command makes it pretty easy to see what commit introduced a line of code and it also makes it easy to see the context of the change (the rest of the diff). I am intimately familiar with `git blame`, and have used it for code archaeology in puzzling codebases over a decade old. It sure beats having nothing, especially when you configure it to ignore whitespace changes and use Magit's lovely blame interface to move through history quickly, but it can still be a pain to figure out where code really originated from. If the originating commit gives me a link back to the issue that started it and the code's well documented, I don't need more verbosity. > There's no reason that it can't be recorded in both places. There's no reason it can't be recorded in fifty places. That doesn't make doing so a good idea. > If you looked at the commit message instead, you can get an explanation and the context of the change (meaning the other parts of the code that relied on the original change you're looking at). You are describing looking at a commit, not the message. By definition the code changes are not part of the commit message. At the end of the day, what I described in my comment is something I arrived at after years of writing verbose messages and slowly realizing it wasn't the best way. You are, of course, free to disagree. Do what works for you.

u801e 8y ago
> Code review ought to catch comments that haven't been updated. There are a lot of people who just look at the diff and not the rest of the code when reviewing. If the comment doesn't appear in the context lines, they may not catch it. > if a change would have caused the comment to become stale and irrelevant to the project's current state, the commit message would have the same problem. Not really. Unlike a comment that can be seen with the current code base, a commit with an outdated message tends to show up in very few lines (if any) in the git blame output for a particular file. For example, in a code base I deal with, the first commit for a particular file where the message explained the rational and some implementation details now only shows up in git blame output for certain blank lines in the file since most of the file has changed in the years since that commit was made. > but it can still be a pain to figure out where code really originated from. You may want to look into the -S and -G parameters of the git log command. They can be used to see when some text was added, removed or moved. > If the originating commit gives me a link back to the issue that started Until you encounter the situation where those links are useless because the system they linked to was migrated to a new platform. Had the actual text been there, then it still would have been useful. > the code's well documented In my experience, code comments rarely explain why a change was made. But if the associated commit message does contain that explanation, then it makes it much easier to see the context of the change. > There's no reason it can't be recorded in fifty places. > > That doesn't make doing so a good idea. That also means you don't have to look in multiple places to find the information you need. The further the documentation is removed from the code, the more likely parts of it will be inaccurate due to changes in the code base, so if you only record documentation in a contract or wiki, then it's very likely that contract/wiki may not be completely accurate. > You are describing looking at a commit, not the message. By definition the code changes are not part of the commit message. You can see both by running git show sha1_from_git_blame. > At the end of the day, what I described in my comment is something I arrived at after years of writing verbose messages and slowly realizing it wasn't the best way. I've spent years encouraging people to write verbose commit messages for changes they made. I've found them very useful (especially in cases where the person who wrote them no longer works for the company and they're no longer around to ask for further clarification). Whenever I come across a commit message that doesn't explain why a change was made and have to ask the person who made it what they were thinking, I invariably think that it would have been much better if their explanation was in the commit message in the first place.
- NateEag 8y ago
  To clarify, I'm not arguing against commit message bodies entirely. They're valuable and I write them regularly. Not for every change, but lots - maybe sixty - eighty percent. I'm just saying that huge, multi-paragraph essays are often a sign you're putting information in the wrong place. I should also add I'm a big believer in small, focused commits - I fairly often will have a branch that has a few hundred lines changed and twenty commits. You make a good point about the issue tracker dying - I've worried about that but have yet to encounter it in practice. Reducing the impact of such an event is probably a good reason to denormalize a little there.

u801e 8y ago

> Code review ought to catch comments that haven't been updated. There are a lot of people who just look at the diff and not the rest of the code when reviewing. If the comment doesn't appear in the context lines, they may not catch it. > if a change would have caused the comment to become stale and irrelevant to the project's current state, the commit message would have the same problem. Not really. Unlike a comment that can be seen with the current code base, a commit with an outdated message tends to show up in very few lines (if any) in the git blame output for a particular file. For example, in a code base I deal with, the first commit for a particular file where the message explained the rational and some implementation details now only shows up in git blame output for certain blank lines in the file since most of the file has changed in the years since that commit was made. > but it can still be a pain to figure out where code really originated from. You may want to look into the -S and -G parameters of the git log command. They can be used to see when some text was added, removed or moved. > If the originating commit gives me a link back to the issue that started Until you encounter the situation where those links are useless because the system they linked to was migrated to a new platform. Had the actual text been there, then it still would have been useful. > the code's well documented In my experience, code comments rarely explain why a change was made. But if the associated commit message does contain that explanation, then it makes it much easier to see the context of the change. > There's no reason it can't be recorded in fifty places. > > That doesn't make doing so a good idea. That also means you don't have to look in multiple places to find the information you need. The further the documentation is removed from the code, the more likely parts of it will be inaccurate due to changes in the code base, so if you only record documentation in a contract or wiki, then it's very likely that contract/wiki may not be completely accurate. > You are describing looking at a commit, not the message. By definition the code changes are not part of the commit message. You can see both by running git show sha1_from_git_blame. > At the end of the day, what I described in my comment is something I arrived at after years of writing verbose messages and slowly realizing it wasn't the best way. I've spent years encouraging people to write verbose commit messages for changes they made. I've found them very useful (especially in cases where the person who wrote them no longer works for the company and they're no longer around to ask for further clarification). Whenever I come across a commit message that doesn't explain why a change was made and have to ask the person who made it what they were thinking, I invariably think that it would have been much better if their explanation was in the commit message in the first place.

NateEag 8y ago
To clarify, I'm not arguing against commit message bodies entirely. They're valuable and I write them regularly. Not for every change, but lots - maybe sixty - eighty percent. I'm just saying that huge, multi-paragraph essays are often a sign you're putting information in the wrong place. I should also add I'm a big believer in small, focused commits - I fairly often will have a branch that has a few hundred lines changed and twenty commits. You make a good point about the issue tracker dying - I've worried about that but have yet to encounter it in practice. Reducing the impact of such an event is probably a good reason to denormalize a little there.