Hacker News Reader

Comment by jefftk | Hacker News Reader

Information that can be automatically extracted from the delta is the least important part of a good commit message. I can figure that part out from looking at the commit later. Instead, what I really want to know is why you made the change. What is the context? What problem were you solving? Why this way and not other ways you might have solved the problem?

A summary of what the change does is still useful, and I'm glad this can now be automated, but it's not the main benefit of a well written commit message.

View on HN

Came here to make the same comment.

There is a great blog post about it: https://dev.to/jacobherrington/how-to-write-useful-commit-me...

It boils down to the following commit message template:

  <what you changed>

  because <why it was needed>

Design decisions should really go into docs rather than commits.

Out of three (commits, comments, docs), the commits are least approachable, just few changes in the code will erase original commit in the blame.

By all means write good commit messages, but crystallize the info in them into changelog or other docs every bigger release

Design decisions are not the "why"s. Commits are point in time checkpoints why development took a certain path. Let's take an example.

If a what looks like this: Store user full name in session table

The why can look something like this:

The full name is authoritatively stored in the user database and should be looked in using the user name. However, during deploys of the Raticate system, the cache gets invalidated and we need to quickly refresh it. This leads to a thundering herd system, as in incident 5244. By caching the full name in the session table we sidestep this problem entirely.

The reason why the Redis cache was not chosen for this data is because the session object is handed to the checkout system for processing, which can for security reasons, as described in document 7745, not access Redis.

And why that should not be in the docs or comments but in some random commit that people will only read when it shows up in git blame ?

When you find a bug later on related to a specific commit, the "why" in the commit can help explain the "what" that resulted in a bug.

It's all in addition to the changelog and other documentation if following a defined release methodology.

Personally I like having the "why" in a comment (with a pointer to the bug tracker item) if adding code. That doesn't work as well when deleting code, and for that, the commit message works as well as anything else.

It’s much easier to find the commit that added a piece of code than the doc

If the doc is on Confluence, you'll probably never find it.

In some workflows, commit messages in the release branch are the changelog. It usually involves squashing or merge commits.

That's one way but it requires a lot of discipline, and even then you'd have to manually go thru them to fish any "commit A introduced something, commit Z reverted that 40 commits after coz reasons" out of it.

From my experience people rarely read the commit message s, so it is better to put the why part into comments in the code, not git history. I mostly write the detailed why part in the commit only for refactoring changes.

My experience is that many changes span several blocks of code in a repo, so there's not always one single location to put the comment. There's also a blessing in that git commits don't need to be maintained like comments. Comments can drift if not maintained. A commit is only observed in-context.

Most developers seem to be poor "commit historians" by default, I'll admit. If you have the energy and consistency to enforce good history, it eventually becomes self-sustaining.

Why write meaningful commit messages at all then? Should we perhaps “git commit -m foo” all the time and call it a day?

My experience here varies wildly; I’ve worked on projects where commit history was carefully maintained and documented, as well as on projects with random squashing or random commit messages. Both had their own benefits and came with a cost too.

For larger, more complex or more mature projects, going through git history can be a common task. So here I’d prefer meaningful commit messages; git blame/bisect/etc gets easier, and sometimes any additional piece of docs has immense value. For smaller, simpler projects or prototypes, where history isn’t used that often, I don’t care that much.

Not proud of it, but honestly > 50% of my commit messages are "wip" or similar.

Source backup is one of my primary uses for SCC, and when I step out for lunch, or need to knock off for the day, I commit where I am, and push with a "wip" (work in progress) message.

The feature branch name I merge is probably the most useful. It's an aggregate of all my commits and what I'm working on.

I do this too, but when I come back from lunch I git reset HEAD~1 and keep going till I have a meaningful piece of work to commit on its own. You can also use interactive rebase to reorder or squash commits if you realize that for readability reasons it makes more sense for a refactoring you started later to appear earlier in the stack or for a subpar commit and its subsequent fixup to be combined. This makes the final history more easy to read for reviewers, and (after it's merged) more easy to read for future you and other devs on the project too.

interactive rebase is (IMHO) the golden ticket for this. Unfortunately, if you're using git as a backup then that means you pushed the commits, so a `git push -f` will be required. I do that all the time and think in general we are unnecessarily scared of it. As long as you're the only person working on the branch, a push -f is NBD. Never do it to master though or a shared branch unless you plan to bring donuts or something in later as an apology.

Yeah where I work, we strongly encourage interactive rebase on solo feature branches.

In fact, even the hairiest long-lived branches can get cherry-picked apart into several "layers" of branches to get reviewed and merged piecemeal. It's really easy if you're starting from too many commits. It gets harder (not impossible) if individual commits commingle said layers.

The commit message is also for future me. Future me doesn't remember what today me can easily recall about the last week of debugging and reverse engineering about how the system works. A thorough commit message can really help when trying to figure out bisect bugs point to a particular commit or to better understand individual lines of code when reviewing code with git blame.

If I'm adding something weird and funky that requires a long explanation of context, it goes in a comment (or even an ADR). If I'm removing it, it goes in the commit message.

(Those are not the only situations, of course.)

Are the commit messages not helping because people are not reading them, or are people not reading them because they are not helpful enough?

I find the latter quite common.

Well, there's one particular exception that I find super relevant -- my own commit messages. There are a number of times when I know I made a code change, and can't remember why, and my own commit messages in the git log remind me.

Hopefully as a side benefit others also find them helpful, but my present self is always grateful to past-self's conscientiousness!

Well, sometimes, changes are "events" and only make sense to know in the context of the state of the codebase at the time.

The main reason i read commit messages, is when i change some code i want to know why it was introduced in the first place to ensure i am not regressing some feature. The why is important, even if its just to know that there is no big story.

From my experience, people rarely write meaningful commit messages or comments in code, and they expect you to just glean everything you need to know by simply reading the code itself.

I read a lot of commit messages. I love exploring repositories and it always makes my day when I find detailed messages about interesting issues.

I do both. Information of the actual behavior of the code as comment, and information about the changes of the behavior in the commit.

depends, if you are bisecting the commit messages are very helpful

Yeah it's not either/or, you really want both.

I like to put the why first. Makes it easier to follow.

Was looking at the examples (link posted at another comment) and this addon seems like a good starting point for an accurate commit message.

Starting point. After that it should up to the committer to make modifications and upstream the message. For those cases, seems good enough for me.

Haven't tried this solution but my first thought was of those (.NET) libraries that would generate comments using a functions signature (function name, parameter name, etc.). Remember some senior devs at the company I worked for at the time being mesmerize and overusing this. We ended up with comments that could easily be inferred from reading the signature...

I like those in general because you can hover over a function call in visual studio to see a description.

A summary can still help you remember the parts of what you did and more accurately fill in the why.

I think you would be surprised how PRs work in many companies. We are encouraged to write small PRs and many will have automated tools that points to a Jira ticket in the description or as a comment. For this reason many leave empty descriptions. In such cases this would still help.

I disagree. Unless there’s some smarter way to do this, I use the commit messages to find the kinds of historical changes I’m curious about. I want to know what changed. I’m not sure how one would do this unless they’re looking at every commit.

The “why” goes into the PR and more importantly, engineering documentation and inline comments.

Plus, a commit message seems woefully plain and too short to properly communicate these things.

The beauty is that this isn’t prescribed. We can all do what makes sense for our contexts.

> The “why” goes into the PR …

This just ensures that the “why” is lost when someone comes looking years later.

From experience, SCM history is far more durable than just about any other work product we produce.

Over five decades later, commit history was still available for the Unix sources and could be reconstructed: https://github.com/dspinellis/unix-history-repo

I’ve used 35-year-old commit messages to help understand a long-standing issue, decades after all other related organization tooling and data had disappeared.

What I have always been told for writing good commit messages is that the message should tell you what the commit does when applied to the code. The place for these what/why messages would appear to be in a ticketing system of some kind, referenced by ID in the commit message.

What you're asking for would result in extremely bloated messages.

On the contrary, git commit messages and checked in docs are the only places that are guaranteed not to be lost to history. Ticketing systems change, get migrated to with data loss or are access limited. Git is forever. The commit message is a much better place for explaining what was done why than some obscure Jira instance.

> The place for these what/why messages would appear to be in a ticketing system of some kind, referenced by ID in the commit message.

No. It's best to assume that all information in your ticketing system will be totally lost.

The commit message should have the "what/why" directly in them, because that's where you'll first look when you want to find that out (why add an extra hop), and it would require extreme incompetence (which is not unknown) to lose information stored there.

I agree at a gut level with this. Do you have a source that this is more widely believed? I would like to bring this to my tech lead.

> I agree at a gut level with this. Do you have a source that this is more widely believed? I would like to bring this to my tech lead.

This was learned from hard experience.

During my tenure, we've migrated corporate wikis/"collaboration systems" four times, and we've used at least as many ticket systems. We also migrated from webex to Teams a few years ago. Each migration resulted in at best a severe partial loss, and in some cases a total loss. The most stable resource is the codebase.

Basically, whenever anyone does a migration for you, they will lose things, and they might even think losing them is a "clever" shortcut that will make them more efficient. Our recent documentation system migration only covered documents modified in the last year as a corporate cost-saving measure, and we were on our own for everything else. Weak/understaffed teams did a bad job. They retroactively implemented a retention policy on Webex that wiped out a lot of valuable recordings, and then the coup-de-grace was the migration to MS Teams, which wiped almost everything else (basically everything that the original recorder didn't conscientiously download and save). We recently migrated to MS ADO as our work tracking system, and that was the only time I've seen old stories/bugs migrated at all, and even then we still lost all embedded images.

Here's a list of things in order of least to most likely to be lost:

1. Head/tip of your project in source control

2. Source history

3. Documentation stored in a central location as files you can easily copy

4. Documentation stored in some system (like a wiki)

5. Tickets/stories in your work tracking system

Walk through a hypethetical ticketing system migration with your tech lead. Assume all external links are broken, and see how expensive it becomes to answer questions about your own codebase. "why did we add special case X? is it still applicable? It interferes with new feature request Y, can we remove it to reduce total risk/cost of implementing Y?"

Integrating with another tool is fine, but not at the expense of your commit history!

There's no meaningful limit on message length for a reason. Don't bury the context in some external system that may change or go offline, let it live in the commit where it is safe and easily accessible.

> extremely bloated messages

Please read a few commit messages for the git project itself.

That is how git was designed to be used. Maybe that provides some perspective of just how bloated commit messages can be, but also how useful they then become.

On my tests the GPT3 is able to understand the whole context and give a very good commit message.

Do you think it was able to answer jefftk's questions, especially

* What problem were you solving?

* Why this way and not other ways you might have solved the problem?

Or do you think those aren't usually needed for a very good commit message?

> * What problem were you solving?

That the ticket was open

> * Why this way and not other ways you might have solved the problem?

This is first one that worked.

There, that's those answers covered for like 80% of the developers

This commit sets the value of variable x to 10 on line 253 of the file main.go

Reply on news.ycombinator.com