5. Writing Commit Messages#
Okay, so you’ve written some code, and now you want to commit what you’ve done, and it comes time to write that -m message. In a rush, you just write “doing stuff” or leave another cryptic remark. Why do commit messages matter anyway?
Image Source: https://aibolik.com/blog/git-commit-messages
5.1. Why Commit Messages Matter#
When you’re working on a project, whether it’s a personal project or part of a larger team effort, writing good commit messages might not be the first thing on your mind. But trust me, investing a bit of time into crafting clear, concise commit messages pays off big time. Commit messages help you understand the story of your code, and can make debugging or reverting back to a certain version, much easier. They help you understand what might have caused your code to break and offer other people insights to your code bases development processes. Writing good commit messages, like many of the other parts of git we’ve seen, are really important to working in collaborative spaces. So, how do you write a good commit message?
5.2. Keep It Brief but Informative#
Your commit message should be like a well-chosen tweet: brief yet informative. Start with what you fixed, and aim for a single line summary of what your commit does. Think of it as a headline for a news article—make sure it’s engaging and to the point. For example, instead of “Fix stuff,” try “Fix login error on user profile page.”
5.3. Use the Imperative Mood#
Write your commit messages as if you’re issuing a command. This might feel a bit weird at first, but it’s a convention that helps maintain consistency. Instead of “Fixed the bug in user login,” write “Fix bug in user login.” It’s like you’re telling the code what to do: “Add feature” or “Update documentation.”
Image Source: https://www.alchemists.io/articles/git_commit_anatomy
5.4. Explain Why, Not Just What#
Sometimes, it’s not just about what changes were made, but why they were necessary. If a commit addresses a bug, explain how it was fixed or why it was important. For example, “Fix null pointer exception when user data is missing in profile view” is more useful than “Fix null pointer”
5.5. Separate the Summary and Details#
If you need to provide more context, separate the summary from the details. Start with a short summary (under 50 characters) followed by a blank line and then a more detailed explanation if necessary.
5.6. Be Consistent#
Consistency is key to good commit messages. Follow the same structure and style throughout your project. If everyone on your team adheres to the same conventions, it makes it easier to understand the history of changes.
Image Source: https://medium.com/@hritik.jaiswal/how-to-write-a-good-commit-message-9d2d533b9052
5.7. Proofread#
Before hitting that commit button, take a moment to review your message. Typos and unclear language can make it harder for others (or even future you) to understand the purpose of the commit. A little proofreading goes a long way.
5.8. Conclusion#
Great commit messages aren’t just for show—they’re a vital part of project documentation that can save time and reduce confusion. By keeping your messages brief, using the imperative mood, explaining the why, separating summary from details, being consistent, and proofreading, you’ll make your commits more useful for everyone involved.
Happy coding!