undefined | Better HN

0 pointsskrebbel6y ago0 comments

I disagree.

I mean, you're right, but I don't think that's time well spent. This is a commit message, not a blog post. Writing concisely is hard and time consuming.

This was probably written in stream-of-consciousness fashion which strikes a nice balance between time invested and possible future usefulness (if any). I mean, the commit might be useful in the future, but there's also a reasonable chance that nobody except the reviewer of the PR is ever going to read that commit message. (If the OP hadn't blogged about it)

0 comments

BoorishBears6y ago

How is writing concisely more time consuming than this long winded stream of consciousness with multiple quoted command outputs and explanations of non-fixes?

If I come across an error and it takes two commands to fix it, my immediate intuition is a commit message with... the error and the two commands. And that’s extremely quick to write...

It’s definitely not “let me write a detailed account of the last hour of my life”... that immediately feels like it will take much longer

Also to be clear, the rule of thumb I mention is not about “what should you think about, then write down”

It’s a filter on what you were already about to invest effort in writing down.

If you feel like an even shorter message is good enough, that’s great.

Just realize sometimes less is more...

JoshTriplett6y ago

It's the exact opposite of "If it was hard to write, it should be hard to understand". This is "This was hard to debug, so let me make it easy to understand and give you (or future me) the hard-won information I just discovered so that you don't have to go through what I did".

If the information took you a great deal of effort to get, that suggests it may be valuable to share. That may not be the right time to attempt to cut out some of that information for brevity, especially if you don't know what the future reader of the message might need to know.

BoorishBears6y ago

What information in the concise version I gave is missing, that causes you to go through additional effort?

I think you edited this in after my reply:

> If the information took you a great deal of effort to get, that suggests it may be valuable to share.

I think this is the core of where we disagree. I often spend insane amounts of time debugging something, only to find the solution was quite simple and unrelated to what I tried.

Often the amount of time you spent debugging is because the search space for your solution was unbounded, not because each step you took was particularly relevant to the actual solution.

To me a commit message should be able hopefully narrowing that search space, not documenting the original unbounded one.

1 more reply

hipnoizz6y ago

"I didn't have time to write a short letter, so I wrote a long one instead."

I definitely agree with BoorishBears - too much unnecessary details in this commit message. Of course it is much more preferable than "Fix template", "Fix utf8" or "fix" which is all too common. But if someone spent 1 hour fixing a problem and then probably 5-10 minutes working on the message then adding 5 minutes to make the message concise should not be a big deal, right? (Who am I kidding ;-))

We use Gerrit at my company, so pushing the change is just a first step. I routinely read my commits after they are pushed for review and many times there are one or more additional changesets because I thought I found something worthy to add to the commit message.

j / k navigate · click thread line to collapse

0 comments

BoorishBears6y ago

How is writing concisely more time consuming than this long winded stream of consciousness with multiple quoted command outputs and explanations of non-fixes?

If I come across an error and it takes two commands to fix it, my immediate intuition is a commit message with... the error and the two commands. And that’s extremely quick to write...

It’s definitely not “let me write a detailed account of the last hour of my life”... that immediately feels like it will take much longer

Also to be clear, the rule of thumb I mention is not about “what should you think about, then write down”

It’s a filter on what you were already about to invest effort in writing down.

If you feel like an even shorter message is good enough, that’s great.

Just realize sometimes less is more...

JoshTriplett6y ago

BoorishBears6y ago

What information in the concise version I gave is missing, that causes you to go through additional effort?

I think you edited this in after my reply:

> If the information took you a great deal of effort to get, that suggests it may be valuable to share.

I think this is the core of where we disagree. I often spend insane amounts of time debugging something, only to find the solution was quite simple and unrelated to what I tried.

Often the amount of time you spent debugging is because the search space for your solution was unbounded, not because each step you took was particularly relevant to the actual solution.

To me a commit message should be able hopefully narrowing that search space, not documenting the original unbounded one.

1 more reply

hipnoizz6y ago

"I didn't have time to write a short letter, so I wrote a long one instead."

j / k navigate · click thread line to collapse