Level Up Your Commit Messages With These Tips!

At some point, we’ve all come across a commit message we don’t understand. In my opinion, every team should create a list of commit guidelines or conventions(and stick to it). You might be wondering, why is it so important to right good commit messages?

Why Write Meaningful Commit Messages?

Commit messages are a way of communication between the team. Let’s say there is a bug in the application in part ‘x’. The person who is trying to fix it only has to see commit messages regarding part ‘x’. A well written commit message can save a great deal of time finding the recent changes related to a bug.

Being a new member of a team and working on projects we haven’t seen before has its challenges. For example, you just joined a team and have been asked to integrate AWS S3 buckets in portion of the application. However, you have not been provided the credentials and the codebase is too large to manually search through the config files. But, the same file upload is already implemented in another part of the application and you just have to extract it into a reusable component.

You can go to the commit list and search for messages with “AWS S3”, look for the files which have changed and start refactoring! Now, let’s look at 7 tips to write better commit messages.

1. Specify the type of comment

• feat: for feature addition
• fix: for bug fixes
• refactor: for changing the way a code block is written without changing the final result
• style: for style changes(CSS/Sass etc)
• test: anything and everything about testing
• docs: documentation addition/updates
• chore: code maintenance

Do not restrict yourself to these types, feel free to add more types of comments but be consistent across the code base.

2. Never assume another developer understands the original problem i.e. the reason for the commit

I recently started working on an existing codebase along with 3 developers. Me and another dev just started working on the codebase. On the second day, when I woke up to pull the latest code to my database I see this:

When I looked at it, I had no idea what the problem was. After about 15 minutes of chatting back and forth, I finally understood the original problem.

Just a single paragraph, that’s all I ask. One paragraph describing the problem containing 2–3 lines. It will help you too in the future, when you come back later trying to fix a bug.

3. Limit the subject line to 50 characters

50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what’s going on. The VScode source control also gives a warning when the characters in the subject go over 50.

Github will truncate commit messages(the subject line) over 72 characters

4. Separate commit heading from body with a blank line

Leave a line between the heading and the body to ensure the reader clearly understands the separation. Also leave a blank line after each paragraph

5. Don’t write irrelevant stuff in commit messages

Until now, it may seem that we should always write large commit messages but there’s a limit for everything. Don’t write your entire life story in there, be short, clear and concise.

Do:

I’ve written a brief description because the example was quite simple, but don’t hesitate to give more details. But remember, be concise and clear.

Do Not:

6. Explain “What Changed” And “Why” Instead Of “How”

State the original problem and why you had to use change it. Then, (in detail), state how the your code changes the way the application works currently. Also, if there is some improvements to be made, specify that too.

To Not Do:

To Do:

Feel free to add more details in the problem/solution. I’ve written in short, because there is no more relevant details I can add.

7. Use Emojis in your commits(GitMoji)

Using emojis to start your messages are very helpful when scanning through a long list of commits. VSCode has a handy extension called Gitmoji that helps us to add emojis at the start of the comment.

After installing that extension from the marketplace, you can see a “smiling” emoji in the source control panel.

After clicking on the “smiley face”, a menu will open with various emojis and their explanation written on the right.

Here’s how a commit with an emoji looks:

That’s it for this post guys. I hope you liked it. Do post other conventions you follow in the comments. Follow me for more such content on twitter. Bye 🤘