"A good commit shows whether a developer is a good collaborator." — Peter Hutterer, Linux.

Years ago, I never realized there were specific rules for writing commit messages until my curiosity got the best of me. I used to think that straightforward messages like “added feature 2,” “fixed the bug on the Main Navigation bar,” or even “foo” were sufficient. The conviction that commit messages went largely unread proved mistaken. In reality, well-crafted commit messages are indispensable, ensuring that our future selves benefit from our diligence and thoughtfulness.

Why You Should Care About Writing Clean Commit Messages

Commits serve as the tangible building blocks of a programmer’s craft. They act as the icing on the cake of code, and when written correctly, they bring substantial value. A well-written commit message becomes indispensable because they provide context — otherwise, a commit message wouldn’t be needed in the first place.

"A good commit shows whether a developer is a good collaborator." — Peter Hutterer, Linux.

Common Mistakes in Commit Messages

Before diving into the rules, let’s address some common mistakes developers often make:

1. Vague Messages

• Example: “Fixed it”
• Why it’s bad: This provides no context on what was fixed or where.

2. Too Much Information

• Example: “Refactored the entire application, fixed all bugs, added new features, updated documentation.”
• Why it’s bad: This makes it difficult to pinpoint what exactly was done.

3. Irrelevant Details

• Example: “Had coffee, then fixed bug #1234”
• Why it’s bad: Personal anecdotes don’t belong in commit messages.

The 7 Rules for Writing Perfect Commit Messages

1. Keep It Short and Sweet

• Limit the subject line to 50 characters or less.
• Example: “Add user authentication”

1. Use the Imperative Mood

• Think of your commit message as a command.
• Example: “Fix login bug” instead of “Fixed login bug” or “Fixes login bug”

1. Separate Subject from Body with a Blank Line

• Helps in readability and clarity.
• Example:

Add user authentication

Implemented JWT for secure authentication.
Updated user model to include password hashing.

1. Capitalize the Subject Line

• Example: “Update README with installation instructions”

1. Do Not End the Subject Line with a Period

• Example: “Improve performance of data fetching”

1. Use the Body to Explain What and Why, Not How

• Example:

Refactor user service

Split the user service into smaller, more manageable functions.
This will help in maintaining and testing the code more efficiently.

1. Be Consistent

• Maintain a consistent style across all commit messages.

Case Study: From Bad to Good

Bad Commit Message:

Fixed issue #456

Improved Commit Message:

Resolve issue #456: Fix null pointer exception in UserService

The null pointer exception was occurring due to an uninitialized object.
Added a check to initialize the object before accessing its properties.

Tips for Writing Better Commit Messages

1. Think Before You Type

• Reflect on what you’ve done and why it matters.

1. Use Tools and Templates

• Utilize commit message templates to ensure consistency.

• Example template:
  

Subject: [TASK] - Description

Body: 
- What was done
- Why it was done
- Any additional notes

1. Review Before Committing

• Always read your commit message before finalizing it.

1. Collaborate with Your Team

• Discuss and agree on a commit message convention with your team.

Conclusion

Writing good commit messages is an art that every developer should master. They are not just a formality but a crucial part of the development process that aids in understanding the history and evolution of a project. By following these guidelines, you can ensure that your commit messages are clear, concise, and valuable to your team.

By adopting these practices, you’ll not only improve your own workflow but also enhance collaboration and productivity within your team. Remember, a good commit message is the hallmark of a diligent and thoughtful developer. So, next time you’re about to commit, take a moment to craft the perfect message.

That's all for today.

And also, share your favourite web dev resources to help the beginners here!

Connect with me:@ LinkedIn and checkout my Portfolio.

Explore my YouTube Channel! If you find it useful.

Please give my GitHub Projects a star ⭐️

Thanks for 23428! 🤗