Rob Pike on good commit messages (2014) • Hacker News Board

Re: Rob Pike on good commit messages (2014)

#21

Post by safog » Thu, Dec 19, 2019, 4:31 PM UTC

caiocaiocaio wrote: post #2

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

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.

Re: Rob Pike on good commit messages (2014)

#22

Post by axaxs » Thu, Dec 19, 2019, 4:32 PM UTC

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.

Re: Rob Pike on good commit messages (2014)

#23

Post by nemetroid » Thu, Dec 19, 2019, 4:33 PM UTC

amelius wrote: post #8

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…

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?

For me it's definitely in the first category, and I take my time writing good commit messages.

It also serves as a good filter for commit content. If you can't write a good, comprehensive commit message for it, it probably shouldn't be its own commit.

Re: Rob Pike on good commit messages (2014)

#24

Post by metalliqaz » Thu, Dec 19, 2019, 4:34 PM UTC

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…

but that is almost entirely about formatting and cosmetics. I don't give a flying fart about line wrapping if the comment adequately explains the reasoning behind a change.

Re: Rob Pike on good commit messages (2014)

#25

Post by deanmoriarty » Thu, Dec 19, 2019, 4:37 PM UTC

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.

I tend to put comments around VERY tricky pieces of code, but the rest belongs to the commit log.

I feel code comments tend to rot because they are not as immutably bound to the code they describe as a commit message is, and for the most part my commit messages are too verbose to end up in code comments, it would create too much clutter.

I have a good integration with my editor that shows inline blame annotations for the current line (and full message is a keystroke away).

Re: Rob Pike on good commit messages (2014)

#26

Post by ivl » Thu, Dec 19, 2019, 4:37 PM UTC

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.

Re: Rob Pike on good commit messages (2014)

#27

Post by pm215 » Thu, Dec 19, 2019, 4:37 PM UTC

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.

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 stage and contextualises all the code they're about to read.

Re: Rob Pike on good commit messages (2014)

#28

Post by getpolarized » Thu, Dec 19, 2019, 4:41 PM UTC

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 could be refactored.

I try to put them directly on methods/functions more and not on specific lines of code.

If I have to document a line of code it probably is a sign that it should be a function/method itself as it's a bit too funky to just stand alone.

Commit messages are GREAT for tracking down when something is broken though.

Would be nice to have your IDE take your code comments and make commit messages for new methods and the documentation for that method/class.

Re: Rob Pike on good commit messages (2014)

#29

Post by axaxs » Thu, Dec 19, 2019, 4:42 PM UTC

pm215 wrote: post #27

axaxs wrote: post #22

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

Both good points to consider - thank you.

Re: Rob Pike on good commit messages (2014)

#30

Post by ses1984 » Thu, Dec 19, 2019, 4:42 PM UTC

deanmoriarty wrote: post #9

amelius wrote: post #8

Earlier quoted context omitted.

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?

It has been an obvious net time gain for my projects. I do a lot of system programming, and often there are very complex reasons why a particular function is called in a non-obvious way, especially after tricky bugfixes. Having a somewhat detailed written record associated with the commit, that won't rot like an inline code comment would, has been very useful in my experience. And all my thoughts become instantly ava…

>that won't rot like an inline code comment would

It's a balance between rot and visibility, right? Unless you code with commit messages always visible, you have to go out of your way to look at them. If the interesting line changes even a little bit, you could hide the commit message explaining everything with one that explains a small change.

If I could only have one, I would rather have comments visible in the code, and control they rot through change review, but of course finding a balance between both is the best.