Effective commit messages are a way for developers to communicate to each other about the changes they’re making to a codebase. These messages can be useful when fixing issues or when finding the root cause of a bug or even when troubleshooting a broken build.

There are many places to learn about writing good commit messages. Hoorvash Nikoo’s guide to commit messages is very useful as is the Conventional Commits website. Here are a few good practices to keep in mind. 

  • There’s no reason not to write a good commit message. You just need a <50-character title and a description, where each line is <72 characters. These character length guidelines help you keep a balance between too much brevity or too much verbosity. If you’re struggling to meet these constraints, it may mean that your commits are too big. In which case, make your commits more atomic.

  • The title of the message should explain the purpose of the commit. This helps someone examining multiple messages identify which commit corresponds to the change they’re looking for. 

  • Describe the commit so anyone looking at it in the future can understand the scope of the change you’ve made, without getting into the code itself.

  • Use integrations so your commits reflect on your task board. These are excellent proxies for status updates. For example, Jira integrates with GitHub, GitLab and BitBucket.

Simple command line tools like Commitzen can teach you to write effective commit messages. All you do at the time of a commit, is type ‘git cz’. The tool will then ask you a few questions and will then create a neat commit message for you. 

Example commit messages by Sachin Dharmapurikar

Previous
Previous

Business decision records (BDRs)

Next
Next

Architectural decision records (ADRs)