Work in software long enough and you’ll eventually need to do some serious digging into the code base to try and figure out why code was done a certain way. Commit messages can be a great tool when digging up the past to uncover these mysteries. Please don’t be that person who makes understanding the past harder. There a two main classes that I believe hinder this; pointless commits and useless commit messages. The following examples are a breakdown of such offenses.
Pointless Commits
When a commit has little to no value by itself I consider it pointless. These serve only to add noise which you have to sift through to obtain anything meaningful. Here are some examples:
The Old “One-Two”
|
|
These are a time honored classic. Back-to-back commits that are really the same thing. What you’ll normally find is the initial addition of a feature or change. Then, after user or automated feedback, more code is written based on that feedback. To prevent these with git, squash the commits together. If the feedback and change are important then document it in the commit message.
Look What I Did
|
This is similar to the old one-two with regards to multiple commits all belonging to a single change. When looking back at git history I couldn’t care less that you’ve cleaned up whitespace or how many times a dependency has been updated. Again, squash these commits together and unify the commit message.
|
Useless Commit Messages
Bad commit messages often leave use asking “why” and “what for”. If you’re looking back through git history you probably don’t care what was done, but instead why it was done.
See Diff for Similar Message
|
Thank goodness the diff has been duplicated for my reading pleasure. This may seem obvious; but in case it isn’t, one can deduce what has changed by looking at the diff patches. I’ll stress it again, why! I understand sometimes the reason is trivial; however, more often then not it’s only trivial to you right now in the context you have. Poor future developer, which could be you, will be lost as hell when debugging why a changed happened?
Sorry Developer, Your Answer lays in a different system
|
|
Ah yes, these take me back to my rpg questing days. Traveling from place to place to find answers is a pain. Not to mention you better pray to god that the source you’ve cited stays around longer then your code repository. Don’t get me wrong, having these as a supplement is fantastic, but they’re just that, a supplement. A general summery of the cited information goes a long way, do it!
A Message is Required to Commit
|
Unlike the diff, these provide zero benefit. These kind of messages appear to be the result of someone begrudgingly typing as little as possible just to satisfy the fact git by default requires it. Replace all of these with “I’d rather not say” and it feels about the same. Please take the time and be courteous to others; fashion an informative message.
A Recipe for Success
Here is the template I try to use:
|