Hacker News Reader

Comment by crazygringo | Hacker News Reader

I've never worked that way.

In my mind, commit messages should be a quick summary of what. The basic motivation should be clearly labeled as a feature, bugfix, etc., but that's all. Commit messages are for quick browsing and a summary of what changed, not extensive justification.

The why is too important to be put in a commit message. The product why belongs in a linked issue that describes the bug or use case in full detail. Meanwhile, the technical why's (why this particular solution as opposed to alternatives) belong in the code itself as comments.

View on HN

The first line (or atleast, the first 80 characters) should be a quick summary - so you can quickly browse via git blame.

But the actual commit message should consist of History/Motivation/Context - so that someone who's going through the blame can understand why a certain change was made, and what the context was.

Linus had a good template for this, which makes a lot of sense: https://gist.github.com/finalfantasia/bd0070673ca27e5f7473

If I want history, motivation and context to actually be read at some point I put it in tests, code comments and README/docs.

If I want my history, motivation and context to be ephemeral I put it in a commit message.

It still perplexes me why people obsess over commit messages while the places where people are actually looking when they have these questions are neglected.

I don't particularly want a commit log at the top of every function, TBH. If I'm looking for the history and context of a change, I want to look at the commit log. If I want a description of the current version, I look in the docs (and yeah, sometime I can only piece together why something is the way it is now by looking through how it's changed. But documenting each change has a much better chance of addressing questions like "why did it work and now it doesn't" then trying to get the docs perfect will.)

>I don't particularly want a commit log at the top of every function

If thats what you got from my comment then you misinterpreted it.

Nobody wants docs to look like commit messages. They want them to be relevant to the context.

{Tests, Code Comments, Documentation} are 3 distinct places to trawl through when quickly going through git blame.

The commit message is one place - and gives the author an opportunity to speak directly with a future developer over the place-in-time-context that this change was made.

Git blame is something you use to ask "what the fuck"? Hence why it's got the tongue in cheek moniker "git blame".

If devs are constantly asking "what the fuck?" all over the code base then that's usually coz tests, code comments, docs and code quality were all badly neglected.

Better commit messages are a band aid over that gaping wound.

You're focusing a bit much on the Developers bit. It's not just Developers who are working through the code-base.

As a lame example - Incident Response/SRE will also be trying to get their heads around changes being made - especially if they're responding to an outage, and trying to figure out what change broke production - and why it was made.

Not everyone will know every bit of the project as intimately as the Dev team - and having a good commit message will help any unfamiliar response team mitigate, or escalate accordingly.

You think incident response would also prefer to go digging around using git blame than just reading your docs?

If you put some effort into your runbooks, not your commit messages, thats where they'll really appreciate good, detailed writing.

Issues are not part of the source code repository. The issue tracker may not be there anymore at some point in the future, and it also may not be accessible when you work offline.

I agree about the technical justifications belonging in the source code itself as comments.

Also when the issue is a bug the information you'll find in the tracker is usually about the symptoms and says nothing about the fix.

> The product why belongs in a linked issue that describes the bug or use case in full detail.

That's nice until you switch git hosts or project management systems and the context is lost. Commits live forever, use them.

At least a small summary of "why" would've been so helpful many times in the legacy codebase I maintain instead of "fix tests", "format", "FOO-123"

Reply on news.ycombinator.com