
Rob Pike on good commit messages (2014) - uluyol
https://groups.google.com/forum/#!topic/golang-dev/6M4dmZWpFaI
======
kstenerud
That's a lovely description of why the fix was needed, but I just took a look
at the go source, and NOWHERE IN THE SOURCE CODE IS THIS FACT DOCUMENTED.

Signals are tricky, temperamental beasts; exactly the sort of thing you'd want
to have comments about in your code. The way things stand, nobody would ever
know why the signals are set up the way they are unless they trawled through
40,000 commits. Yes, 40,000: git log --oneline | wc -l.

I'm all for giving a helpful description of why a commit was needed, but this
is FAR too detailed for a commit message, and belongs in the CODE, which
people will actually be reading while they debug an issue.

As for his other examples of bad commits, "Moved A to B" is not necessarily
bad, unless there was a reason to do it other than to just rearrange where
things lie. Same goes for "Add convenience functions" or "Code cleanup". If
you're not fixing a bug or adding new functionality, you're just doing janitor
work. And that doesn't require detailed descriptions.

Commit messages are to let people know in a concise way why you made the
commit. Comments are to let readers know why you've done things in an
unexpected way, or to describe things they're not expected to be familiar
with, or tricky gotchas.

~~~
fdr
Do not agree. Commit messages can be more expansive than comments, because
comments bitrot more readily: they are not rooted in a time and change to the
code.

I use commits for the largest bulk of explanation, particularly "why," which
can be rather detailed and not of much interest to someone skimming the code
rapidly.

Comments I use for pointers that are unlikely to bitrot and/or important to
prevent error. Except for the most timeless design elements in a project, I do
not commit long documentation.

~~~
stinos
I do follow your reasoning, bad comments are worse then no comments, but in
this particular case it really feels to me like the meat of the commit body
should also be a comment. Just so that when someone looks at the code and
wonders, hmm, why is this flag here, he/she can figure it out without having
to do a blame/log on the file. (Don't get me wrong, great tool, but has it's
own problems).

Judging whether or not comments are permitted on the bitrot-ability of a piece
of code seems hard to begin with, and even then a bit arbitrary. In this case,
the whole comment would be just for that flag. So if someone really just gets
rid of the flag but not the comment, especially on code like this, and that
also passes code review then I think there are more pressing problems then
bitrot.

------
deanmoriarty
After 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 "add x", "fix foo", "fix build", ...). It
became way too frustrating when I looked back at code committed by myself (or
others) years prior and wondered "what is the reason why this code exists?"

These days, every single commit I push has an entire paragraph or two clearly
describing the changes, and the motivation behind them, even if it's a one-
line diff.

My team praises me for this, and I think I've been able to influence the
culture as I see more junior people taking their time to craft good commit
messages and edit their commit history before pushing a PR.

~~~
amelius
Ok, but how much time have you "wasted" wondering what a piece of code was
doing versus how much time would you have wasted writing good commit messages?

~~~
dtech
It's a balance, but I've definitely seen that a good commit title can
massively help newcomers, yourself when you can't remember why something is
the way it is and can be a boon when debugging.

A nice balance I've found is to not care while developing, but then squash all
commits into a single one when merging a pull request and give that a good
message.

~~~
katbyte
This is what I do, means I don’t have to worry about describing a “fix linting
errors” commit. Just on squash merge ensure the commit message captures what’s
required (and on gh the pr is automatically included and I typically put any
linked issues in the additional info area)

------
hprotagonist
At about the same time, Chris Beams wrote this, which I have loved ever since:

[https://chris.beams.io/posts/git-commit/](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 characters
    
        Capitalize the subject line
    
        Do not end the subject line with a period
    
        Use the imperative mood in the subject line
    
        Wrap the body at 72 characters
    
        Use the body to explain what and why vs. how*

~~~
RussianCow
> Limit the subject line to 50 characters

It's nearly impossible to get certain points across in 50 characters. I keep
mine under 72, and even then, I sometimes struggle to adequately describe a
change in that little space, even at a high level, to the point that it would
be useful for someone searching for something.

Honestly, all of this stuff matters way less than the actual content of the
commit message anyway. Style is worthless if there is no substance.

~~~
saagarjha
> It's nearly impossible to get certain points across in 50 characters.

Usually that kind of stuff goes in the body of the commit message.

~~~
RussianCow
But most Git UIs only show the first line of the commit message when
displaying the log, so if you're searching for something specific, you're only
going to see that without clicking into a commit. I want that first line to
tell me whether this commit is relevant to whatever I'm looking for, and it's
extremely difficult to do that in 50 characters.

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

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

I've worked on a couple project that took the approach of documenting the
details of what was done in the bug tracker (or PR/MR), etc, and then just
putting the bug# and a one-line description in the commit history.

In every one of these projects, we ended up later moving to a different bug
tracking system. In some cases the bugs were transferred, but the numbers were
not, in others nothing was transferred. Suddenly all those bug numbers in the
commit history were completely meaningless and useless.

I'm now a strong advocate that the detailed documentation should be in the
commits messages themselves. One of my biggest complaints with gitlab is that
you spend all this time writing a good MR description, and then it has no
mechanism for including that description in the actual merge commit.

~~~
Pxtl
Yeah, for me the approach is that the PR describe the _what_ that was done at
high-level, and the requirement describes the _why_.

That said, MS is good at long-term support if nothing else. Our
TFS/VSTS/DevOps instance is older than dirt so I don't have to worry about
losing history.

------
MayeulC
I also encourage everybody I know to write descriptive merge commits: "Merge
feature X" instead of "Merge someone/master into master". It really helps when
using

    
    
        git log --first-parent
    

to avoid displaying intermediate messages.

This really helps with the so-called "Aligator" [1] workflow: create a merge
commit for every bugfix or feature, instead of just rebasing (you can still
rebase if you want). That makes the history contain more metadata: a bit like
a HN or e-mail thread can be collapsed to filter it out, first-parent helps
filter the noise (implementation details) to display topics.

I wish web UIs such as gitlab's allowed to collapse commit graphs according to
this.

[1]: [https://euroquis.nl//bla%20bla/2019/08/09/git-
alligator.html](https://euroquis.nl//bla%20bla/2019/08/09/git-alligator.html)
(no mention of first-parent in that blog post, unfortunately.)

~~~
ilikepi
> I also encourage everybody I know to write descriptive merge commits...

Or alternatively, use a branch naming scheme that includes a little ticket
metadata: "Merge branch 'feat_4714_default_tag_filter'"

------
stefan_
Then single best commit messages you are ever going to find in any given
project are in the Linux kernel:

[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin...](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/)

~~~
yodsanklai
[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin...](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=6609fee8897ac475378388238456c84298bff802)

Wow, that's a great commit message for one character change!

------
jedimastert
Somewhat important to note that he's talking about change list messages, not
commit messages. Change lists are full sized chunky patches.

~~~
sime2009
True. In git language that is PR level, not commit level.

------
hinkley
I can't help but feel a sense of cognitive dissonance in the fact that we put
such a large degree of importance on a write-once piece of data.

If getting the comments "right" on commits is really that important, then you
should be able to revise them based on new information.

Are they important, or are they only important because you _have_ to get them
right the first time so you have to treat them that way?

(That's a bit of a rhetorical question. I get quite a lot out of walking the
commit histories on code, but often it's the shape of the commit that contains
the information, not the comment)

------
MaxBarraclough
Pike's summary seems pretty spot on: _What, why, and background._ Right on.

I really don't understand the reply in that thread, _" what" doesn't matter
because it's in in the code_.

Of course it matters. The whole point is that you get your bearings from the
comment text, and you only need to look at the code to see the details of the
'how'.

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

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

------
caiocaiocaio
One one hand, I like a nice long commit message. On the other hand, human
nature is terrible.

I know that if long commit messages catch on, some synergetic managers will
start insisting on minimum lengths for commit messages, and start having
meetings discussing standards and policies for commit messages, and start
filling binders with more rules than one person could ever memorize. Soon,
fixing a single-character typo in a comment will take 20 minutes, and pressing
enter will be nerve-racking because you know there's just something you're
forgetting from the binder.

~~~
safog
I feel you here, but it's up to tech leads / Sr. Engineers to push back on
management bullshit like this because otherwise the commit messages aren't the
only thing in that culture that'll make an engineer miserable.

My management horror story here is having a SCM (source code manager) who was
responsible for taking code checked into a VCS and deploying it to prod (using
a CI system no less). He used to insist on engineers sending him a word
document with a very specific template on what files changed, what binaries
need to be re-deployed etc. etc. for every single commit or it wouldn't get
deployed at all and his day was made up of yelling at engineers because the
template was incorrectly formatted, or used the wrong font or whatever.

Noone else could touch prod (or even staging) except him and all of this
process originated from an engineer messing up a deployment and bringing down
prod.

My takeaway from this entire experience was tech middle management at smaller,
enterprise-y shops was just completely broken and all these guys were capable
of was playing silly political games. If possible, just work with smart
people, if you can't evaluate if someone's smart during an interview process,
just work for one of the big tech-cos and you can't go wrong.

------
Vysero
It seems like what was said by Austin Clements was more of a bug report than
it was a description of a solution for a bug. Which is the job of reporter and
not the person fixing the problem.

In my mind, a commit message should not be the be all end all for what can be
said about a particular bug fix. If someone needs to know the details then
they can look at the diff and if the person who made the change feels it was
complex enough then they should add a comment on the bug report about what was
changed and how it was changed prior to marking the bug as *fixed.

------
ASalazarMX
This should carry over to version changes visible to the end user. "Stability
and performance improvements" is the equivalent of "Fix bug" commits.

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

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

~~~
iudqnolq
What do you think about committing with one-liners as you develop so that you
can rollback, and then completely rewriting history before pushing?

~~~
pavon
I absolutely agree that you should commit early and often, and that short one-
liners for those commits are fine. It is when you go to merge that you need to
have good messages and there are several ways you can do that, depending on
your team's preferences:

* You can rebase and groom your commits into meaningful sets of changes each with good descriptions (how Linux uses git).

* You can squash all the commits, and always just have a single commit for each merge with a detailed description.

* You can keep your full commit history as a record of how the work was actually done (Fossil encourages this philosophy), but always have a detailed merge commit that can stand-alone in describing all the work done in that merge.

------
clktmr
I recently started to write git commit messages as if I was writing an email
to my future self. It enables me to write the commit message without thinking
too much about what's important. I also tend to write more since, because an
email with just one paragraph is pretty rude.

------
SkyPuncher
Personally, I find little use to stashing a lot into a commit message. Nearly
all work is managed outside of Git.

Provide a short description, reference the work you're doing (a ticket, a PR,
etc), and hold the discussion there.

Rebase many, meaningless commits into a single one for integration purposes.

~~~
RussianCow
I used to believe this as well, but then a company I worked for switched away
from GitHub (we used GitHub Issues prior), and we lost _all_ of that
information. Commit messages are immutable, whereas anything else can easily
disappear or become inaccessible.

------
jgrahamc
Totally agree: [https://blog.jgc.org/2013/07/write-good-commit-
messages.html](https://blog.jgc.org/2013/07/write-good-commit-messages.html)

------
drej
A somewhat related discussion:
[https://news.ycombinator.com/item?id=21289827](https://news.ycombinator.com/item?id=21289827)

------
topaztee
wrote a little post on just this [https://www.topaztee.com/markdown/git-
commit-message/](https://www.topaztee.com/markdown/git-commit-message/)

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

~~~
MayeulC
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).

------
mcslearner
> What's really sad is how often I find myself telling people this. It should
> be part of our culture...

Somehow I don't think whining about this problem on some google group is going
to help.

~~~
practical_lem
It isn't "some google group", it's the golang-dev mailing list.

------
briandear
[https://tbaggery.com/2008/04/19/a-note-about-git-commit-
mess...](https://tbaggery.com/2008/04/19/a-note-about-git-commit-
messages.html) (2008)

