Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Rob Pike on good commit messages (2014)

groups.google.com

Post reply on HN
Print view View original

61–70 of 98 posts

Re: Rob Pike on good commit messages (2014)

#61

Post by julik »

alunchbox wrote: post #56
deanmoriarty wrote: post #4

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…

Assuming you're doing Git based flow branching off of Develop or Master to do changes. Before merging your changes back in do you rebase and cleanup the messages or squash? I feel like every company I work for just does merges everywhere and history is 99% unreadable at this point without filtering out certain things on the log and even then. Any tips on how you're able to keep things clean for the entire team ? What…

We disabled merge commits on all of our repositories on Github, and rebase is used seldom - meaning that when you do merge you are presented with an edit box for the squashed commit message. This incentivises one to actually write good prose inside that box. We are not perfect but getting there.

Re: Rob Pike on good commit messages (2014)

#62

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

Re: Rob Pike on good commit messages (2014)

#63

Post by nguoi »

genzeddev wrote: post #13
deanmoriarty wrote: post #4

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…

I think part of the issue is that for someone who's been writing English for 15 years, knocking out 2 paragraphs of cogent explanatory prose is as easy as ABC. But for someone who is relatively new to the English language, this can be the source of much anguish and frustration. Doubly so for something like a commit message that is immutable by design. The idea of a typo, a bad idiom, or even worse, unintentionally of…

Fundamentally, I think you are correct, however my English-second-language friends/colleagues tend to write better English when it's in a structured fashion - like a commit message or in documentation - than they do colloquially. That is how they learned it, after all, while native speakers learn it from osmosis. It's rare to see the ESL speakers use the wrong there/their/they're like native speakers do.

Re: Rob Pike on good commit messages (2014)

#64

Post by lhorie »

getpolarized wrote: post #28
deanmoriarty wrote: post #4

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…

I've been a Software Engineer for 15 years now... 10 years in the industry as a systems engineer before that. I sort of agree but what I try to do is put more comments and documentation in the source code directly. The problem is that commit messages are usually hidden only when there's a problem. Comments are there for the life of the code. The problem with comments though is that they could go stale and something c…

It doesn't need to be an either/or affair. Often times, I'll add a comment to a particularly tricky piece of code, but then also comment in the commit message (and then again in the PR in Github for the code reviewer)

Often times, even a copy-paste is better than nothing. Better to over-communicate

Re: Rob Pike on good commit messages (2014)

#65

Post by mannykannot »

axaxs wrote: post #22
deanmoriarty wrote: post #4

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…

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.

When a straightforward piece of code is replaced by another, it can still be useful to know why.

Being able to seamlessly browse the history of a given function is one of the things a fully integrated development environment should support.

Re: Rob Pike on good commit messages (2014)

#66

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

Re: Rob Pike on good commit messages (2014)

#67

Post by Pxtl »

pavon wrote: post #55
Pxtl wrote: post #39

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 an…

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

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.

Re: Rob Pike on good commit messages (2014)

#68

Post by giancarlostoro »

deanmoriarty wrote: post #4

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…

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

I used to do this, but prefer the list form. I like to note what has been added or removed, if you're searching through the commit history it's all useful.

Re: Rob Pike on good commit messages (2014)

#69

Post by morelisp »

iudqnolq wrote: post #47
getpolarized wrote: post #28

Earlier quoted context omitted.

I've been a Software Engineer for 15 years now... 10 years in the industry as a systems engineer before that. I sort of agree but what I try to do is put more comments and documentation in the source code directly. The problem is that commit messages are usually hidden only when there's a problem. Comments are there for the life of the code. The problem with comments though is that they could go stale and something c…

Jetbrains can be set to show you the last commit message that modified a chunk of code. I assume there's a way to do this in vim/emacs for the sufficiently motivated as well.

This is basic functionality via `git annotate` (which goes back, at least, to `cvs annotate`).

It is also built into Emacs as `vc-annotate` (default `C-x v g`), though `magit-blame-addition` is a better option for projects using git.

Re: Rob Pike on good commit messages (2014)

#70

Post by iudqnolq »

morelisp wrote: post #69
iudqnolq wrote: post #47

Earlier quoted context omitted.

Jetbrains can be set to show you the last commit message that modified a chunk of code. I assume there's a way to do this in vim/emacs for the sufficiently motivated as well.

This is basic functionality via `git annotate` (which goes back, at least, to `cvs annotate`). It is also built into Emacs as `vc-annotate` (default `C-x v g`), though `magit-blame-addition` is a better option for projects using git.

Awesome. Was missing that in emacs. Magit continues to surprise and delight me.
Post reply on HN