This was post was first inspired by the Erlang Repo.
While I may not always be the best at following this wisdom. I have significantly increased my ratio of "good" commit messages to "bad" commit messages.
Past Tense vs Present
Since I know this can turn into a bit of a holy war I will just cover it and move on.
Most people are trying answer the question: What did this commit do?
Added files
Deleted files
but for my commit messages I tend towards the question: What does this commit do? OR What will this commit do?
Add files
Delete files
I believe that a lot of this comes from the fact that when a developer is working on code. That are thinking about what they just did. That's valid, and so I understand why so many trend towards past tense. However, if you are thinking about it from a merging and patching perspective it takes on a lot of different meaning.
Ok, so now that we are beyond that why should we have good messages? If I look back through the commit log and all I see is, "Minor Fix", "Changed Names", "Did some refactoring". When I come back next week or later, those changes aren't going to mean anything to me. Then you have to take the time to delve through all the commits and figure out what has happened.
Instead making commit messages that look like "Update MyTrigger to only accept parameters with a minimum length of 5" or if you're grouping larger efforts you can say things like:
Change Collection Module logging from OkLogger to SuperLogger
- Refactor log statements to abide with the different signature of SuperLogger
- Change dependency from OkLogger to SuperLogger
This may not sound like it would take too much effort, but you would not be live the amount of time that I've saved by having good commit messages. Just like any advice you can take it or leave it, but a little extra time on commit messages can save a lot more later when you're trying to track down why all of a sudden you're getting references to frameworks you thought you removed ages ago.
While I may not always be the best at following this wisdom. I have significantly increased my ratio of "good" commit messages to "bad" commit messages.
Past Tense vs Present
Since I know this can turn into a bit of a holy war I will just cover it and move on.
Most people are trying answer the question: What did this commit do?
Added files
Deleted files
but for my commit messages I tend towards the question: What does this commit do? OR What will this commit do?
Add files
Delete files
I believe that a lot of this comes from the fact that when a developer is working on code. That are thinking about what they just did. That's valid, and so I understand why so many trend towards past tense. However, if you are thinking about it from a merging and patching perspective it takes on a lot of different meaning.
Ok, so now that we are beyond that why should we have good messages? If I look back through the commit log and all I see is, "Minor Fix", "Changed Names", "Did some refactoring". When I come back next week or later, those changes aren't going to mean anything to me. Then you have to take the time to delve through all the commits and figure out what has happened.
Instead making commit messages that look like "Update MyTrigger to only accept parameters with a minimum length of 5" or if you're grouping larger efforts you can say things like:
Change Collection Module logging from OkLogger to SuperLogger
- Refactor log statements to abide with the different signature of SuperLogger
- Change dependency from OkLogger to SuperLogger
This may not sound like it would take too much effort, but you would not be live the amount of time that I've saved by having good commit messages. Just like any advice you can take it or leave it, but a little extra time on commit messages can save a lot more later when you're trying to track down why all of a sudden you're getting references to frameworks you thought you removed ages ago.
No comments:
Post a Comment