2 ms·

I agree with your first paragraph, but I don't think it's super relevant to the article: the why of a commit usually takes some time to explain, and the subject

I agree with your first paragraph, but I don't think it's super relevant to the article: the why of a commit usually takes some time to explain, and the subject line is nowhere near sufficient, so that usually goes into the first paragraphs. For non-trivial commits I try to follow the "why, what, how" template: first explain the issue / concern / background for the change, then clarify the change if the diff is not super obvious or is a bit large, and finally explain the implementation changes if there were options. In my experience the former and latter are the most important when blame-diving, I want to know the context / driving force / use case for a change, but I also want to know the scope of consideration, because e.g. sometimes I'm thinking of a fix which was considered and rejected for still-valid reasons, while at other times it was just considered unnecessary back then (YAGNI) or the blockers have since been removed. Either way the subject needs to be snappy, so that it can quickly be selected for consideration or not e.g. if I'm blame diving and I see a commit which just does indenting / formatting, I probably can skip over it without looking at the actual change.

twodave 3y ago
I mostly agree, though if I could only have “what” or “why” I would choose “why” every time. To me this is similar to describing the problem in product design. I wish the “why” was more often concise enough to be the prominent feature in a commit, because commits are difficult/annoying to amend (I’d be surprised if more than a couple people where I work knew how) and if something is going to be left out, it is the “why”.
- masklinn 3y ago
  Can't disagree with that. I think the order of importance is why > how > what, because the first two are the least likely / possible to infer from the commit contents. So an explicit record is most crucial.

twodave 3y ago

I mostly agree, though if I could only have “what” or “why” I would choose “why” every time. To me this is similar to describing the problem in product design. I wish the “why” was more often concise enough to be the prominent feature in a commit, because commits are difficult/annoying to amend (I’d be surprised if more than a couple people where I work knew how) and if something is going to be left out, it is the “why”.

masklinn 3y ago
Can't disagree with that. I think the order of importance is why > how > what, because the first two are the least likely / possible to infer from the commit contents. So an explicit record is most crucial.