It is easy to miss good solutions. The best type of solution is the one that feels natural, hence invisible. Good commits tend to fall into that spectrum.
For those who aren’t fluent in programming lingo, commits are a way to save the state of our work, like you’d save your progress on a videogame.
Git commits allow us to go back to a specific point in our progress to see or revert changes made to a project. Since projects are often worked on between multiple people, the safe states come from all the members working on it.
A commit is mainly made up of:
- a unique identifier
- file(s) changes
- a message
All of these items are accessible to the people working on the project.
What is a Commit Message?
Focus not on the what but the why.
Developers have access to both a unique identifier and the file changes. This leaves the message with the high order responsibility to contain everything else. A commit message is the description of the state outside of the file changes.
The message should be able to fill in the following sentence: “IF APPLIED, THIS COMMIT WILL _________” without describing the code changes.
Generally, we code in packs. Just like another relationship, communication is essential. These git messages are a way to tell a story, and we should take advantage of that. When we successfully understand our code as affecting others, we can begin tackling major issues impeding progress. Progress halts when
- we feel frustration out of code that makes no sense to us.
- We feel ineptitude while looking for new ways to do a previously done task.
- We feel hopeless while working on code we have no background on.
The following is an example of a commit message that lacks empathy:
commit ce820a9da Author: ren-rocks Date: Mon Feb 4 11:23:07 2021 -0500 quick fix
What is a Good Commit Message?
commit b3ed56c94a7 Author: ren-rocks Date: Mon Mar 1 23:02:47 2021 -0500 fix bad parsing due to v3.1 API changes changes to the NYT API response broke the regex string. this change removes patch ce820a9dd. The new regex handles both endpoints. endpoints updated: topStories and latest. an alert has been added to check for future API changes so we do not go through this again. find the new alert in card 38t90
Aside from the general commit rules, a good commit message
- explains why the change is needed
and has at least a few of the following:
- has keywords that help searches
- tells other developers how the author arrived at that fix
- teaches about the new tools or the repo
- sounds human, not robotic
Ideally, we can make each other’s lives easier. I hope this post helps to do that.