Hacker News Reader

Comment by neilkk | Hacker News Reader

The thing is that writing a good commit message for future people doing `git blame` is only worth it if it's a line of code which someone in the future will look at and need to know why it was changed from its previous form to the current form.

If you simply want to comment the current state of the code, you should add a comment in the code.

No one will ever need to know in the future why that particular space character is an ascii space, so the whole commit message is just a blog entry in the wrong place.

It would have made sense to just put a comment at the top of the file saying "make sure encoding is whatever".

View on HN

Then don't write commit messages for the future, write them for reviewers.

Seriously, as somebody who reviews a lot of code, well-written commit messages are a godsend.

It's an awful shame that GitHub doesn't allow commenting on commit messages. It's as if GitHub is being run by people who just don't know how Git is meant to be used.

> It's an awful shame that GitHub doesn't allow commenting on commit messages.

You actually can comment on a commit itself. I'm in the habit on middle-clicking on the sha1 link of commits in a PR and looking at the commit itself. You can comment on lines in the commit, and there's a text area at the bottom where you can comment on the entire commit itself. I'll then follow up with making a comment on the PR linking the commit (pasting the sha1 link) and saying I made a few comments here.

> It's as if GitHub is being run by people who just don't know how Git is meant to be used.

Github wasn't really designed with code review in mind. A lot of the features they added over the years for review appear to be hacked on rather than fixing fundamental design issues (like being able to comment on commit messages without having to jump through a bunch of hoops).

Review systems like gerrit, phabricator, review board, or even email, do a much better job at exposing individual commits and their associated metadata like the commit message.

I don't think they were suggesting to review the individual commits, rather the (individual) commit messages. Commit messages are text, so you could have a similar line by line click-and-comment review interface as you already have for the code changes.

> I don't think they were suggesting to review the individual commits, rather the (individual) commit messages.

That's a good point.

> Commit messages are text, so you could have a similar line by line click-and-comment review interface as you already have for the code changes.

It would be nice if something like that was available in Github. The closest thing you could do would be to copy the commit title and body and paste it as quoted text in the text area and then comment on it inline.

I write commit messages for future-me. Sooner or later I'm going to encounter the same problem again and wonder how I solved it last time. If I have a vague inkling that I dealt with this before, all I have to do is searching through my commit history and I can find it again. I can search my author (me), I can search by date, I can search by what files I touched. It's lovely.

> Seriously, as somebody who reviews a lot of code, well-written commit messages are a godsend.

This is the issue; are commits in your codebase for the reviewers? Or for FutureDev to see what the hell happened? These are often very different things, and most process models favor one of these at the total expense of the other.

Interesting that you perceive a dichotomy there, can you elaborate where you see the conflict?

As a reviewer, I see myself as a (extremely near, time T+epsilon) future developer who is trying to see what the hell is happening.

There's a dichotomy between a history of actual code changes, oopsies and redos included, and "a carefully crafted story of the intent of this change". One is an ugly reality, the other is a pretty story of intention. The process vs. the final result.

Both are useful, but in different contexts. The latter is good for a PR, but when optimized for that often loses a lot of other context, and is meant to be a throwaway bit of data that once the PR is approved, never seen again, nor meant to be seen again.

The former can delve a bit into what experiments were tried and abandoned and can give a lot more meaning to the final result.

> As a reviewer, I see myself as a (extremely near, time T+epsilon) future developer who is trying to see what the hell is happening

I generally find this to not be the case; reviewing is to see what this might "break" and has IME been extremely transactional.

Not all PRs nor reviewers are like this of course, and you may not be one. But, again, IME, this is the "modern" workflow.

> The former can delve a bit into what experiments were tried and abandoned and can give a lot more meaning to the final result.

I haven't found this to be true at all. Commits don't tell me anything other than when the coder left their desk for the moment. When there's a policy that allows people to have a "rough, ugly history", where a coder chooses to commit is completely arbitrary. I would argue that the clean, crafted story is the only helpful one.

You can argue that a coder shouldn't be committing unless they are at a natural milestone that can be annotated, but I would consider that the "crafted" story.

Sometimes a comment is appropriate. Sometimes a commit message is appropriate. Sometimes I need both. Often when dealing with legacy code I find neither. I'd be happy with either.

A commit message lets me tell a short story about a change that touches multiple locations in the code base. Maybe no one part of the change is all that tricky.

A commit message also allows me to explain why I'm making the change, whereas a comment may explain why the code is the way it is.

Commit messages and comments have overlapping use cases, but the Venn diagram is not a circle.

$0.02.

>Sometimes a comment is appropriate. Sometimes a commit message is appropriate. Sometimes I need both.

And often your get neither...

    The thing is that writing a good commit message for future people doing `git blame` is only worth it if it's a line of code which someone in the future will look at and need to know why it was changed from its previous form to the current form.

Well what about this example: I removed a few lines of code and explained in the commit message why I thought it was correct to do that. If somebody (possibly me) comes looking for that code and realizes it's not there, they'll be much happier to see some sort of explanation rather than a "removed lines" message.

Regarding commenting in the code vs. in the commit message, sometimes I copy-paste my explanatory comment if there is one into my commit message.

Right. You've given an example of exactly what I said was the only reasonable use case for detailed info in the commit message: someone in the future will need to know the history of that particular piece of code. It seems like the point of your specific example is to say 'in some cases you might want to know the history of a gap'. Fine. That seems like a nitpick to me.

No one in the future will need to know the history of a particular ascii encoded blank space (among a whole file of ASCII encoded blank spaces). Anyone who needs the general info that the file needs to be ascii will be helped by it being somewhere else, as opposed to in a random commit message.

But virtually every diff is one that someone in the future might want more information on. You can't know that they won't until you get to the end of the future and haven't needed it.

All communication is communication with people in the future.

> the whole commit message is just a blog entry in the wrong place.

Right. All this wonderful information and detailed error messages need to be findable by someone searching the same error. Someone digging into the code is a very different use case and they need a tiny fraction of that information.

The example in the blog post would be a much better example if some kind of test or linting step was added to catch these white-space errors, to explain the need for catching such errors.

Pro tip, you can write both comments and commit messages.

> If you simply want to comment the current state of the code, you should add a comment in the code.

I think you mean "past state of the code"...

These comments rarely get updated. My favorite recent one was several sentences describing a data structure and how it mapped out statuses, written about a decade ago. Barely a year after that comment and its code was written, the entire thing was re-written with completely different structure - and the comment left unchanged. Left a co-worker completely baffled due to inexperience with perl, we figured out what happened because of svn blame.

The drifting of code from comments is a problem I would love to see solved.

I've seen tools that can compare the git commit dates of code with nearby comments and that's a good start. However, there are potential problems with that, such as code and the comments that discuss the code not being near each other; or the code being updated and there being no need to update the comment

I think literal programming might help here, but that's an entirely different topic really.

Looking for more advanced tools that that and I suppose we're into the world of AI - asking the tool to understand both the code and the comment and to compare the underlying meaning.

Code review is an option but outside of an organisation that's difficult to do and besides, I think the problem would be best solved by something that is repeatable and part of the build process. And I'd love to be able to have a git commit hook that can say, "hold on! you've updated code but there's a comment that now looks old". That's the dream.

Mistakes can happen. But if code comments are frequently not updated as the code evolves, it is a level of lazy that will probably manifest in other ways as well.

Reply on news.ycombinator.com