4 ms·

In my opinion, unless your project already has excellent documentation, you shouldn't spend much time or thought documenting your commits. Making detailed comm

by cool-RR 17y ago

In my opinion, unless your project already has excellent documentation, you shouldn't spend much time or thought documenting your commits. Making detailed commit messages is "documenting the process". Making code documentation is documenting the product. The latter, in my opinion, is much more important.

kscaldef 17y ago
I disagree. Good commit messages also document the product. They should describe or reference features requested, bug reported, and the _why_ of the change at least as much as the _what_ of the change.
jonursenbach 17y ago
Let us know how that works out 6 months from now when you have a regression issue and you're trying to track it down.
tetha 17y ago
In fact, I currently experience the very unintuitive thing that I can create extremely detailed commit messages using git without investing much more time (at the moment, I need to spend around 5-10 additional minutes after an hour or two of development while getting a precise log of added functionality and/or refactorings performed). The thing I am currently investigating is to commit extremely often during development and then use rebase to squash all of these extremely tiny changes into the actual change. Don't come with the "atomic single changes"-stick after me for squashing local commits, because when I said extremely tiny, I meant extremely tiny. Currently, I commit pretty much whenever a new test is red or the last red test is green, or after a single refactoring step. Given that, I end up with a very detailed sequence of steps and changes I made. Once you are done then, you can just add a summary line, a quick paragraph explaining the reason for those changes and reformat the previous commit messages into a (hieraichally structured) list of detailed changes. I can just repeat this: Doing this is almost no noticeable overhead (it's just a git commit -a -m "Move method: Foo.bar -> Bar" after a successful build and some rebasing eventually, which takes 5 - 10 minutes after an hour or two of development) and massively improved my commit messages.

by cool-RR 17y ago

kscaldef 17y ago

I disagree. Good commit messages also document the product. They should describe or reference features requested, bug reported, and the _why_ of the change at least as much as the _what_ of the change.

jonursenbach 17y ago

Let us know how that works out 6 months from now when you have a regression issue and you're trying to track it down.

tetha 17y ago

In fact, I currently experience the very unintuitive thing that I can create extremely detailed commit messages using git without investing much more time (at the moment, I need to spend around 5-10 additional minutes after an hour or two of development while getting a precise log of added functionality and/or refactorings performed). The thing I am currently investigating is to commit extremely often during development and then use rebase to squash all of these extremely tiny changes into the actual change. Don't come with the "atomic single changes"-stick after me for squashing local commits, because when I said extremely tiny, I meant extremely tiny. Currently, I commit pretty much whenever a new test is red or the last red test is green, or after a single refactoring step. Given that, I end up with a very detailed sequence of steps and changes I made. Once you are done then, you can just add a summary line, a quick paragraph explaining the reason for those changes and reformat the previous commit messages into a (hieraichally structured) list of detailed changes. I can just repeat this: Doing this is almost no noticeable overhead (it's just a git commit -a -m "Move method: Foo.bar -> Bar" after a successful build and some rebasing eventually, which takes 5 - 10 minutes after an hour or two of development) and massively improved my commit messages.