4 ms·

Why should the commit message explain why? I thought the point was to give a summary of the changes so that you don’t have to read the full diff.

0x008 4y ago
Because it is very useful down the road to understand why you used implementation x and not implementation y.
jkukul 4y ago
I think that one doesn't exclude the other. You can still write a multi-message commit with two messages: 1. Short summary of what is being changed 2. Explain WHY I think the point is that even if 1. is missing it can be worked-back by reading through the diff. But if 2. is missing then the future generations have no way of finding out reasons behind some decisions.
kolinko 4y ago
The summary of changes can be inferred, or generated automatically with gpt ;) "Why", on the other hand can be lost. Especially during refactoring. Let's say you removed some assertion / safety check from a function, because you verified that it's not necessary there. Without explaination in a commit, someone may not get your reasoning. Same thing with renaming variables, reordering the code etc. Comments may be useful in some cases, but in many cases there won't be a right place to put them in.
charcircuit 4y ago
A commit message is made of a title and a body. There is usually more context on why a change was made than can fit in the title.
OJFord 4y ago
The subject line should be 'why': Fix 500 due to syntax error accessing /users the body can summarise and expand on (..if you know what I mean) the diff as well as explaining why: Due to <arcane language reason> in this case <syntax> was interpreted as a baz, when clearly the author in <blame commit> intended foo, which would return the response with bars here as expected. This commit fixes the issue by adding an explicit semicolon, thus forcing the foo interpretation. That's probably overkill for a simple syntax error (unless it really is that arcane in which case it might be a bit of a teaching moment/object lesson). Compare: Add semicolon [no body]
- scotty79 4y ago
  First version sounds passive-aggresive.
  - OJFord 4y ago
    The exact wording really isn't the point, I see what you're saying but it's not what I intended - that's just the lack of a concrete example (something actually arcane and counter-intuitive) making it more difficult. I was imagining writing it from the perspective of 'this took a good bit of looking into why it didn't work like it looks like it should have'.
    - scotty79 4y ago
      I'm not sure if it's accidental. Too much detail just sounds as if you not only fixed something but also lodged a formal complaint against whoever touched that place first. Technically it's good because it's very informative and probably noone will read it unless you, yourself made a mistake and the thing you fixed still doesn't work for some cases. Just sounds weird. But I'd still prefer it to "Added semicolon" for a commit diff that adds semicolon and nothing else. At minimum I'd like to see a link to a ticket that this change is supposed to solve.
splix 4y ago
What's the point of the summary? But "why" is very important for the future code owners. Year or tho later someone else adding a new fix may have a question about the existing parts to avoid breaking them. And the only thing he can rely is `git blame` to figure out "why it's implemented in this particular way"

0x008 4y ago

Because it is very useful down the road to understand why you used implementation x and not implementation y.

jkukul 4y ago

I think that one doesn't exclude the other. You can still write a multi-message commit with two messages: 1. Short summary of what is being changed 2. Explain WHY I think the point is that even if 1. is missing it can be worked-back by reading through the diff. But if 2. is missing then the future generations have no way of finding out reasons behind some decisions.

kolinko 4y ago

The summary of changes can be inferred, or generated automatically with gpt ;) "Why", on the other hand can be lost. Especially during refactoring. Let's say you removed some assertion / safety check from a function, because you verified that it's not necessary there. Without explaination in a commit, someone may not get your reasoning. Same thing with renaming variables, reordering the code etc. Comments may be useful in some cases, but in many cases there won't be a right place to put them in.

charcircuit 4y ago

A commit message is made of a title and a body. There is usually more context on why a change was made than can fit in the title.

OJFord 4y ago

The subject line should be 'why': Fix 500 due to syntax error accessing /users the body can summarise and expand on (..if you know what I mean) the diff as well as explaining why: Due to <arcane language reason> in this case <syntax> was interpreted as a baz, when clearly the author in <blame commit> intended foo, which would return the response with bars here as expected. This commit fixes the issue by adding an explicit semicolon, thus forcing the foo interpretation. That's probably overkill for a simple syntax error (unless it really is that arcane in which case it might be a bit of a teaching moment/object lesson). Compare: Add semicolon [no body]

scotty79 4y ago
First version sounds passive-aggresive.
- OJFord 4y ago
  The exact wording really isn't the point, I see what you're saying but it's not what I intended - that's just the lack of a concrete example (something actually arcane and counter-intuitive) making it more difficult. I was imagining writing it from the perspective of 'this took a good bit of looking into why it didn't work like it looks like it should have'.
  - scotty79 4y ago
    I'm not sure if it's accidental. Too much detail just sounds as if you not only fixed something but also lodged a formal complaint against whoever touched that place first. Technically it's good because it's very informative and probably noone will read it unless you, yourself made a mistake and the thing you fixed still doesn't work for some cases. Just sounds weird. But I'd still prefer it to "Added semicolon" for a commit diff that adds semicolon and nothing else. At minimum I'd like to see a link to a ticket that this change is supposed to solve.

splix 4y ago

What's the point of the summary? But "why" is very important for the future code owners. Year or tho later someone else adding a new fix may have a question about the existing parts to avoid breaking them. And the only thing he can rely is `git blame` to figure out "why it's implemented in this particular way"