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

81–90 of 98 posts

Re: Rob Pike on good commit messages (2014)

#81

Post by rhmw2b »

kstenerud wrote: post #62

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

At Google (the original audience of the "rant") tools like Moma and Code Search make it much easier to find the relationship between commit messages and code, so it makes more sense to avoid duplicating information in comments. Finding the commit message for a line of code literally takes one press of a button.

If it's really tedious to find relevant commit logs then I think the right answer is to improve the search process rather than compensate with more comments.

Re: Rob Pike on good commit messages (2014)

#82

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

Re: Rob Pike on good commit messages (2014)

#83

Post by hinkley »

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…

We have a precommit hook that insists on a ticket being in the commit message, which helps.

Except some idiot migrated our bug database to a new server and re-numbered the tickets in the process, so only the last two years are intelligible.

Re: Rob Pike on good commit messages (2014)

#84

Post by hinkley »

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 also think it's more important to think of a commit as a performance piece. The words matter but the shape is more durable.

You can comment the commit all you want, but if it contains three separate and unrelated activities then the commit will still be 'muddy', whereas 3 commits with bad comments but one activity per is far more legible.

Remember, nobody is reading your commit messages, your tests, or (probably) your documentation unless something is already wrong. Then they're already stressed out and trying to grovel through your information. They're already biased toward being grumpy. Don't add onto that. I'm only reading your commits trying to figure out if a bug is a feature poorly realized or not, so I don't break something else.

Re: Rob Pike on good commit messages (2014)

#85

Post by cornishpixels »

kstenerud wrote: post #62

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

> NOWHERE IN THE SOURCE CODE IS THIS FACT DOCUMENTED. The referenced commit (https://github.com/golang/go/commit/675eb72c285cd0dd44a5f280...) has /* SIGSETXID; see issue 3871, 9400 /, / SIGCANCEL; see issue 6997 */

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

git blame exists. 675eb72c285 src/runtime/os1_linux.go (Austin Clements 2014-12-19 16:16:17 -0500 417) var sa sigactiont

Re: Rob Pike on good commit messages (2014)

#86

Post by Pxtl »

bendavis381 wrote: post #74
Pxtl wrote: post #46

Earlier quoted context omitted.

Yeah, I just mean the PR process auto-squashes/rebases instead of merging, so that junior developers don't have to think about it. The problem is that if somebody leaves the branch up (delete-on-merge is obviously preferred), or derivative experimental branches, you can't tell if it's been merged or not because the commit hashes are different after the rebase. The branch list has become a scary basement.

Check out how phabricator handles this. It's essentially what you're asking for: https://secure.phabricator.com/phame/post/view/766/write_rev... TL;DR: PRs are not based off a diff between master and a remote branch. Instead, phabricator sends up patches to code review and when approved, the Phabricator tooling handles the rebase locally. No remote branches and clean history.

That's an interesting fix although I'm unsure about the sense in discouraging pushing changes.

It seems like the chief benefit they tout - clean history - is already handled by the auto-squash-and-delete approach. The real problem is the difficulty in cleanup of secondary or undeleted branches.

It isnt' really what I was asking for, though. What I want is a "soft-squash" where the intermediate commits aren't deleted, rather they're just hidden from history. The ability to draw a dotted line around a region of the DAG and say "treat this blob like it was one commit for all intents and purposes unless I say otherwise.

Re: Rob Pike on good commit messages (2014)

#87

Post by sa46 »

hprotagonist wrote: post #3

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

Interestingly, in the 3rd post in the submission, Pike specifically avoids mandating a style guide.

> I would rather not turn this into rules and style guides, just a widespread understanding that a changelist description is worth taking some time to write.

Re: Rob Pike on good commit messages (2014)

#88

Post by petters »

rhmw2b wrote: post #81
kstenerud wrote: post #62

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

At Google (the original audience of the "rant") tools like Moma and Code Search make it much easier to find the relationship between commit messages and code, so it makes more sense to avoid duplicating information in comments. Finding the commit message for a line of code literally takes one press of a button. If it's really tedious to find relevant commit logs then I think the right answer is to improve the search…

Having worked at Google, agree 100%. I think people at Google expect people to look at the commit message more than at other places because it's so easy.

Re: Rob Pike on good commit messages (2014)

#89

Post by stefan_ »

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…

> I don't want to require that juniors and student developers waste their time curating their history

Uhm, one of just the most important skills for junior developers to learn is to tackle a larger change through a succession of individually logical, atomic changes.

Re: Rob Pike on good commit messages (2014)

#90

Post by kspacewalk2 »

xorcist wrote: post #76
kstenerud wrote: post #62

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

> "Moved A to B" is not necessarily bad There is always a reason why things are 1) done and 2) done in this specific way and not another. It is also relevant if this is part of a larger change and it there are external dependencies on this commit. These things must be clear from the commit message. > you're just doing janitor work That makes it sound like janitorial work does not require complete commit messages whic…

Git tools may be routed in email, but they most certainly aren't used that way by most people. Why would I write a commit message like I'm writing an email if both the commit message and email are the wrong tools for the job? We have issues are PRs for code discussion within the context of code. This priceless information should live with the repo. Not in some isolated silo like email which is not accessible to people who aren't on the chain, or commit messages that are difficult and time consuming to traverse in any but the simplest and smallest repos.
Post reply on HN