Commit messages done the right way

We have all seen it. You see something in your source code. You do not know why it was added. And you look at the commit history. And then you see: “fix bug” or “add feature name”. How helpful is that message? In this blog post I will address how you can write commit messages that are helpful. And optimized for the reader.

So, why is this important?

Most agile teams need peer reviews. The most common or well known way is via pull requests. When you introduce a change. For a feature or fixing a bug. The question your peer reviewer will have is: Why this change was made. And then continues to look at the changes. You create a pull request on one or more commit messages. A commit describes the why of a change. When you create a pull request you can use these commit messages when you create your pull request.

Example commit

fix input

Or:

fix: white spaces on input

Remove the leading and trailing spaces. This will clean the input before we save it to the database.

Issue: #123

This is the difference between writing a commit message. And writing a useful commit message. Useful commit messages explain why the change was made. When you create a pull request you can use the commit messages as input. And draft a useful pull request description for your reviewer.

Commit format

I am a big fan of the conventional commits format. But the most important thing is that you write down why the change was made. Not what the change is. The changes are already displayed when you do a diff between commits/branches. So describing what has changed does not make sense. The reason why that is in the authors head. And unless you add it in a commit message that information gets lost. By doing this you create a better historical overview. And it makes it easier to create pull requests.

Conclusion

When you optimize your commit messages for the reader. The reader does not need to go on a scavenger hunt. And it creates a better historical overview of why changes are made in your repository.