One problem with commit messages is that they get overwritten. Often code is refactored multiple times so the original good quality commit messages are hard to find amongst upgrading/refactoring/moving/cleaning messages. Makes me wish for comments perhaps.
Rob Pike on good commit messages (2014)
31–40 of 98 posts
Re: Rob Pike on good commit messages (2014)
#32One problem with commit messages is that they get overwritten. Often code is refactored multiple times so the original good quality commit messages are hard to find amongst upgrading/refactoring/moving/cleaning messages. Makes me wish for comments perhaps.
Github has the nice ability in its `git blame` column to show the previous commit for chunks in cases where somebody does a large-sweeping cleanup commit. I often wish git-blame had the option to show this as well.
Re: Rob Pike on good commit messages (2014)
#33After being in the field for almost a decade now and guilty of so many poor commit messages, I came to the firm realization that a very important trait of a good software engineer is the ability and diligence to write detailed commit messages, and I would have never remotely imagined this during the first few years of my career (I was "raised" in companies who didn't care at all about this and all commits were always…
What in your opinion is the benefit/difference of this, versus commenting nonobvious code? I tend to prefer the latter. Each time I work on someone else's code, I'm elated if they write longform comments about what they're doing or why. I think tracking down commit messages would be more cumbersome.
In my experience I don't see them as mutually exclusive. Good comments in code should still be in place. In my opinion the git history should not explain what the code does necessarily but instead the nature of the changes that were made. In my experience projects are significantly easier to manage if commits are squashed into larger commits that have (1) a clear title, (2) clear summary of what was done, and (3) some link to the tickets in JIRA with the full details. In the short term it may not make a big difference but once you have years of history in a single project as well as many hotfixes or releases the better organization of git makes the project easier to manage.
Re: Rob Pike on good commit messages (2014)
#34I follow the format of the first line being a tag with a short one line description, followed by a new line, followed by further explaining of the what and why.
Example:
"Fix: router now asynchronous.
Our previously implementation of a synchronous router was causing a 30% slowdown when tested with `wrk` (hyperlink to utility used to test)."
with an additional link to a Jira ticket if the particular commit addresses one.
Seems to float well with everyone I've worked with.
Re: Rob Pike on good commit messages (2014)
#35Earlier quoted context omitted.
What in your opinion is the benefit/difference of this, versus commenting nonobvious code? I tend to prefer the latter. Each time I work on someone else's code, I'm elated if they write longform comments about what they're doing or why. I think tracking down commit messages would be more cumbersome.
Good comments are important too. But comments describe the code as it is at this point in time ("why is the code doing X?"); commit messages describe the change ("why are we making the code do X rather than Y?"). Sometimes the same information should go in both places; but the focus and emphasis when you're writing the description up varies. A good commit message is also really useful for code reviewers: it sets the…
To add to that, probably at length:
Some information is a pre-requisite for understanding a specific block of code. This information is a great fit for comments, because everyone who's looking at the code will need to know it, and having it in a comment ensures that it's discoverable.
Other information is a pre-requisite for understanding the engineering or business decisions that motivated a design decision, but isn't necessary for understanding how the code works or how to interact with it. That makes it less appropriate for comments, because the comment would just be clutter (light pleasure reading at best) under the most typical use case. People who are engaging in those use cases should know how to use git blame to find what they need.
For still others, the unit to which the information applies is not a block of code; it's a set of changes. In those cases, comments are a terrible choice for conveying that information. Maybe a commit message is better. If it's not, you probably need to be looking to a project wiki or some separate documentation files, so that the information can be written and maintained in one place. You can still use comments, but they should merely cross-reference the centralized documentation. Today's copy/paste is tomorrow's outdated and misleading misinformation.
Re: Rob Pike on good commit messages (2014)
#36At about the same time, Chris Beams wrote this, which I have loved ever since: https://chris.beams.io/posts/git-commit/ I note with some glee that magit colorizes my commit text and flags long lines,etc. largely in the style of this advice. The money: The seven rules of a great Git commit message Keep in mind: This has all been said before. Separate subject from body with a blank line Limit the subject line to 50 cha…
I shared a variation of this with our development managers (consciously changing "rules" to "tips & suggestions" so as not to ignite a tabs v. spaces holy war) and got very strong responses about how "as long as you get a ummary with some context and cosistency, and the issue # linked this is overkill". Okay, well how do we enure that we get this without some guidance? It's very frustrating.
Do the team already have a consensus? Do they believe there’s a problem?
Re: Rob Pike on good commit messages (2014)
#37Re: Rob Pike on good commit messages (2014)
#38I like this. A large description of what's changed does a load of good. What kills me is when using pull requests, putting a complete description into the pull request... and then finding my commits not squashed after my PR is approved.
Well, I usually prefer to write descriptive commit messages for individual commits before opening a pull request. If I feel it needs to be squashed, I will do it myself.
It crushes my heart every time someone squashes my detailed, self-contained commits together.
If there is more information in the PR than in the commit messages themselves, I will add that to the merge commit (see my other comment about merge commits).
Re: Rob Pike on good commit messages (2014)
#39We take a "PR all the things" approach using MS VSTS/DevOps. Every PR needs a work-item attached and a description, and those get cooked into the commit.
We always squash, but squashing is dubious - if the any of the commits of the branch are still kicking around in other branches, it looks like they're ahead when they're not. Imho, this is a huge flaw in GIT - I don't want to squash, but I do want a clean history and I don't want to require that juniors and student developers waste their time curating their history. The fact that there's no way to mark commits as "this is unimportant crap leading up to the merge" in Git is annoying.
VSTS logs the PR number and the relevant work-items in the message so for any given commit it's easy to get back to the PR where you can see the detailed discussion of the change, requirements, etc.
But either way: reviewers enforce useful PR message, and we discard the intermediate commits. This works very well for clean history.
Re: Rob Pike on good commit messages (2014)
#40I follow the format of the first line being a tag with a short one line description, followed by a new line, followed by further explaining of the what and why. Example: "Fix: router now asynchronous. Our previously implementation of a synchronous router was causing a 30% slowdown when tested with `wrk` (hyperlink to utility used to test)." with an additional link to a Jira ticket if the particular commit addresses o…
this makes perfect sense and one should show care when constructing commit messages. That being said, if commit messages require too much care, then folks will start to make less commits as they become rather expensive to do. As with all things in life, when and how often to commit is a balance.