5 ms·

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 loo

by neilkk 3y ago

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

Dylan16807 3y ago
> 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.
tehnub 3y ago
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.
- neilkk 3y ago
  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.
  - thfuran 3y ago
    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.
    - neilkk 3y ago
      All communication is communication with people in the future.
js2 3y ago
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.
- sverhagen 3y ago
  >Sometimes a comment is appropriate. Sometimes a commit message is appropriate. Sometimes I need both. And often your get neither...
cerved 3y ago
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.
atq2119 3y ago
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.
- u801e 3y ago
  > 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.
  - sverhagen 3y ago
    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.
    - u801e 3y ago
      > 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.
Izkata 3y ago
> 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.
- metafunctor 3y ago
  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.
- JetSetIlly 3y ago
  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.

by neilkk 3y ago

Dylan16807 3y ago

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

tehnub 3y ago

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.

neilkk 3y ago
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.
- thfuran 3y ago
  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.
  - neilkk 3y ago
    All communication is communication with people in the future.

js2 3y ago

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.

sverhagen 3y ago
>Sometimes a comment is appropriate. Sometimes a commit message is appropriate. Sometimes I need both. And often your get neither...

cerved 3y ago

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.

atq2119 3y ago

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.

u801e 3y ago
> 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.
- sverhagen 3y ago
  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.
  - u801e 3y ago
    > 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.

Izkata 3y ago

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

metafunctor 3y ago
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.
JetSetIlly 3y ago
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.