You’ve just finished up a big chunk of code, you run your tests, and you’re ready to push it out the door. In your haste, you type up a quick message and think “this is good enough”. A few weeks later, you’re scanning back through your commits looking for a certain change, and you find yourself more often than not having to glance through the code changes of each commit to figure out what that change was really doing. If this sounds familiar to you, you may want to be more reflective with each commit message and think about what you really want to convey.

Here are a few reasons why you should spend a few more moments on that commit message:

1. You likely won’t remember your changes as clearly as you think you will

You may be saying to yourself “These changes are pretty straightforward. I don’t really need to describe what’s happening here.” But in the future, when you weren’t just dabbling in that portion of the codebase minutes before, you may find it more difficult to remember what you were trying to accomplish with those changes. By simply spending a few moments to write a more descriptive commit message, you may save your future self the time (and headaches) that you may have otherwise had to spend figuring out what you were doing in a given commit.

2. Your teammates should be able to easily understand your changes

While I also strongly recommend having easy-to-decipher & self-documenting code, it is important to give the context of why you are making a change. Your teammates will likely want to glance through your code to understand the code changes more in depth, but having that first bit of context before diving in is invaluable.

3. Easily find where a bug may have been introduced

By reading a clear commit message, you should be able to easily recall what change was introduced. If you find a bug in your app related to a certain piece of functionality, you can review the changes made to that portion of the app and more easily narrow down where something may have gone awry.

4. You may need to rollback to a given commit

In the event of an app change that needs to be reverted, commits can be used to determine the last time the app was in a desirable state to roll back to.

5. You may want to find code from specific changes

Even if you don’t plan to rollback to this given commit, you may be looking for a way in which you solved a given problem in the past. If you aren’t able to piece together all of the changes made for a certain feature just by looking at the current incarnation of the code (or would prefer the efficiency of a Version Control System visually presenting these changes), you can view the contents of a commit to neatly see how those changes were implemented.

I’m not arguing for long, verbose commit messages (because let’s be real — no one wants to read a commit message longer than a sentence or so), I am arguing for being purposeful and concise in our commit messages. As a good rule of thumb, try to write your commit messages so that they take no more than 30 seconds for your audience to both read and understand the change.

What are your thoughts on the importance of commit messages?
Let me know in the comments 🎉