5 ms·

That sucks and I know it doesn’t help fix your current situation, but I’ve found it useful to include more context and long comments in commit messages than cod

That sucks and I know it doesn’t help fix your current situation, but I’ve found it useful to include more context and long comments in commit messages than code comments. If your team knows how to use git blame for archeology, the information tends to stay more cogent to the code, while code comments often go stale.

Gigachad 5y ago
It becomes increasingly undiscoverable. Especially after some lint rule changes and the last change becomes the lint fix. Info going stale seems much worse with commit messages since they can’t even be updated unlike comments.
- jhugo 5y ago
  This is largely a problem of GitHub and other code UIs making it awkward to see anything other than the most recent commit in blame view. With `git blame` you can use `-w` to ignore whitespace changes and `-M` to detect moved/copied code; a lot of the time this will help to rapidly find the relevant commit rather than a lint change. You can also use `git log` on a range of lines of a file: `git log -L 15,23:src/main.rs` and if you add `-p` you'll see diffs as well. Comments can go out of date, commit messages (if used properly) provide a genuine timeline of the evolution of the code.
JohnBooty 5y ago
I generally find code comments much more useful than commit messages. They are of course not mutually exclusive and you can (and should) do both. 9 times out of 10, "why are things the way they are now?" is what I'd like to know. Occasionally, of course, I would like to know "why things were the way they were x commits ago" and that's when commit messages come in handy. But that's the minority use case for me.
- jhugo 5y ago
  Interesting. I'm basically the opposite. I use `git blame` heavily and find that I can rapidly understand the intent behind some code by doing so, assuming the commit messages are well-crafted. Comments are great, where appropriate, but to achieve the same density of information you'd have to add a comment with every commit, which would probably result in a difficult-to-read codebase.
  - JohnBooty 5y ago
    I use `git blame` heavily and find that I can rapidly understand the intent behind some code by doing so, assuming the commit messages are well-crafted Me too. Once editors started displaying inline git blame information, it was pretty transformational. But, this bogs down pretty quickly for me. Great for a single line of code, but if I'm trying to understand something that spans multiple methods or multiple files that's a lot of spelunking around the commit messages, which are a mix of whys and whats. At their best, code comments are a really focused distillation of the current whys and should never ever contain whats.
- eloisius 5y ago
  It depends on what kind of commit messages your team writes, and how much "churn" a line of code gets with style changes, whitespace, etc. It requires making smaller, focused commits so the comment is directly relevant to the change, and writing good commit messages that tells you why something is the way it is _now_. I always use `git add -p` to only stage relevant portions of my current work, and then usually write a detailed message like this: Decrease reprojection error threshold to 1.0 With improved calibration, RANSAC has been able to find a similar number of inliers even with a tighter threshold, resulting in better triangulations. <maybe attach some output showing improved reprojection error stats> Now when someone comes upon threshold=1.0 and want to know why this number is what it is, they can get blame it. The latest commit should be enough, but it might also be useful to know why that threshold has changed over the time. The problem with churn can be mitigated by telling git to ignore whitespace changes, but it's not perfect. Maybe more helpful is to have a style guide and make it part of your review process so you don't end up with multiple developers doing things like reformatting a multi-line function call to their liking over and over.
gregmac 5y ago
Interesting, I have always viewed those as very different things. Comments explain non-obvious things. For example, "this is a custom search because it was found to be 2.3x faster than .find() for this use case" or "this is sent as a string for backwards compatibility with ExternalRandomApi v1.2" or just walk through a complex algorithm. I typically only go into archeology mode for two reasons: 1) I found the source of a bug and want to see when it was introduced and why. This is most helpful to prevent reintroducing an old bug, especially in old code lacking unit tests. 2) Someone wrote code that should have been commented, but wasn't.
aetherspawn 5y ago
I think JIRA links are a lot better than huge inline slabs of text in commit messages. Then you can change them later ie make links to other tickets or leave comments.

Gigachad 5y ago

It becomes increasingly undiscoverable. Especially after some lint rule changes and the last change becomes the lint fix. Info going stale seems much worse with commit messages since they can’t even be updated unlike comments.

jhugo 5y ago
This is largely a problem of GitHub and other code UIs making it awkward to see anything other than the most recent commit in blame view. With `git blame` you can use `-w` to ignore whitespace changes and `-M` to detect moved/copied code; a lot of the time this will help to rapidly find the relevant commit rather than a lint change. You can also use `git log` on a range of lines of a file: `git log -L 15,23:src/main.rs` and if you add `-p` you'll see diffs as well. Comments can go out of date, commit messages (if used properly) provide a genuine timeline of the evolution of the code.

JohnBooty 5y ago

I generally find code comments much more useful than commit messages. They are of course not mutually exclusive and you can (and should) do both. 9 times out of 10, "why are things the way they are now?" is what I'd like to know. Occasionally, of course, I would like to know "why things were the way they were x commits ago" and that's when commit messages come in handy. But that's the minority use case for me.

jhugo 5y ago
Interesting. I'm basically the opposite. I use `git blame` heavily and find that I can rapidly understand the intent behind some code by doing so, assuming the commit messages are well-crafted. Comments are great, where appropriate, but to achieve the same density of information you'd have to add a comment with every commit, which would probably result in a difficult-to-read codebase.
- JohnBooty 5y ago
  I use `git blame` heavily and find that I can rapidly understand the intent behind some code by doing so, assuming the commit messages are well-crafted Me too. Once editors started displaying inline git blame information, it was pretty transformational. But, this bogs down pretty quickly for me. Great for a single line of code, but if I'm trying to understand something that spans multiple methods or multiple files that's a lot of spelunking around the commit messages, which are a mix of whys and whats. At their best, code comments are a really focused distillation of the current whys and should never ever contain whats.
eloisius 5y ago
It depends on what kind of commit messages your team writes, and how much "churn" a line of code gets with style changes, whitespace, etc. It requires making smaller, focused commits so the comment is directly relevant to the change, and writing good commit messages that tells you why something is the way it is _now_. I always use `git add -p` to only stage relevant portions of my current work, and then usually write a detailed message like this: Decrease reprojection error threshold to 1.0 With improved calibration, RANSAC has been able to find a similar number of inliers even with a tighter threshold, resulting in better triangulations. <maybe attach some output showing improved reprojection error stats> Now when someone comes upon threshold=1.0 and want to know why this number is what it is, they can get blame it. The latest commit should be enough, but it might also be useful to know why that threshold has changed over the time. The problem with churn can be mitigated by telling git to ignore whitespace changes, but it's not perfect. Maybe more helpful is to have a style guide and make it part of your review process so you don't end up with multiple developers doing things like reformatting a multi-line function call to their liking over and over.

gregmac 5y ago

Interesting, I have always viewed those as very different things. Comments explain non-obvious things. For example, "this is a custom search because it was found to be 2.3x faster than .find() for this use case" or "this is sent as a string for backwards compatibility with ExternalRandomApi v1.2" or just walk through a complex algorithm. I typically only go into archeology mode for two reasons: 1) I found the source of a bug and want to see when it was introduced and why. This is most helpful to prevent reintroducing an old bug, especially in old code lacking unit tests. 2) Someone wrote code that should have been commented, but wasn't.

aetherspawn 5y ago

I think JIRA links are a lot better than huge inline slabs of text in commit messages. Then you can change them later ie make links to other tickets or leave comments.