4 ms·

As a relatively young developer, I have to ask, are comments not a better place to document context? Commit messages are much less discoverable to me than comme

by _bxg1 6y ago

As a relatively young developer, I have to ask, are comments not a better place to document context? Commit messages are much less discoverable to me than comments when I'm looking at a piece of code. I usually put the "why" in comments and the "abstracted what" in commits. Enough info for someone to quickly rule whether or not a commit could have introduced a given bug, since that's usually what I'm looking for when I'm going through commit history.

btschaegg 6y ago
It's different context. If you're explainig why you write a piece of code the way you do, a comment is most certainly helpful. If you're explaining, why you're changing it the way you do, that's where the commit message shines. That's not to say you can't do both for intricate problems. And there are certain things you'll likely don't want to see inside your codebase (like references to bug tracker IDs and so on), which are IMO perfectly fine in a commit message. On the discoverability: Do you use `git blame` much? Because in projects that live a long time, that will most likely be the way you'll discover commit messages the most. And it is very handy in one of those WTF moments to see why and how a particular piece of code was altered, as opposed to "update" or "improve logic". Also: On your notion of "abstract what": That's supposed to be your commit's subject line. The rest of the message then will be the "why". I like to think of it as an email to some future maintainer (e.g. me in a year) on why it was necessary to change a piece of code. Edit: It's also important to see the differences workflow between your project and Linux, which Git was originally built for. In Linux, your change most likely is an email to some maintainer. If it sucks, your code won't be merged. And there's something to be said about being able to vocalize your reason for changing code. I still get the impression that many people who riff on the "return on investment" part of commit messages don't factor in that you're very likely not understanding a problem if you cannot describe it readably in text.

by _bxg1 6y ago

btschaegg 6y ago

It's different context. If you're explainig why you write a piece of code the way you do, a comment is most certainly helpful. If you're explaining, why you're changing it the way you do, that's where the commit message shines. That's not to say you can't do both for intricate problems. And there are certain things you'll likely don't want to see inside your codebase (like references to bug tracker IDs and so on), which are IMO perfectly fine in a commit message. On the discoverability: Do you use `git blame` much? Because in projects that live a long time, that will most likely be the way you'll discover commit messages the most. And it is very handy in one of those WTF moments to see why and how a particular piece of code was altered, as opposed to "update" or "improve logic". Also: On your notion of "abstract what": That's supposed to be your commit's subject line. The rest of the message then will be the "why". I like to think of it as an email to some future maintainer (e.g. me in a year) on why it was necessary to change a piece of code. Edit: It's also important to see the differences workflow between your project and Linux, which Git was originally built for. In Linux, your change most likely is an email to some maintainer. If it sucks, your code won't be merged. And there's something to be said about being able to vocalize your reason for changing code. I still get the impression that many people who riff on the "return on investment" part of commit messages don't factor in that you're very likely not understanding a problem if you cannot describe it readably in text.