Hacker News Reader

Comment by huijzer | Hacker News Reader

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.

View on HN

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.

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.

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

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]

First version sounds passive-aggresive.

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

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.

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"

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.

Reply on news.ycombinator.com