Clear and concise commit messages are essential for maintaining a well-organized project history. Good commit messages provide context, improve collaboration, and make code reviews and debugging much easier. In this blog post, I will cover some essential conventions and best practices for writing effective commit messages. These are my personal insights and approaches that have proven effective in the teams I've worked with in the past and currently work with.

Why good commit messages matter

Commit messages are more than just logs; they're valuable documentation that:

• Explain why specific changes were made
• Help in code reviews and debugging
• Enhance collaboration and project history readability

By following clear conventions, you can make your project's history more accessible for both current and future developers.

Key commit message conventions

1. Keep it short and focused

• Limit the title to 50 characters: The title should capture the main purpose of the commit succinctly. Limiting it to 50 characters keeps it focused and easy to scan in a list.
• Use a descriptive verb in the title: Start with a verb like "Add", "Fix", or "Update" to give quick context.

2. Use Sentence Case for the title

Using title case (e.g., "Add new reset password functionality to login page") gives structure and differentiates the title from a longer description.

3. Skip the period at the end of the title

Avoid punctuation at the end of the commit title; it's unnecessary and maintains uniformity.

4. Add the issue key to the start of the message

Including the issue key at the beginning (e.g. "JIRA-1234: Add new authentication flow" or "#123: Add new logo") ties the commit directly to an issue in your project management tool. This practice makes tracking changes back to specific issues much easier.

5. Avoid URLs in commit messages

URLs can clutter messages. If additional resources are needed, include them in the project's documentation or comments within the code.

6. Add a description when needed

For commits requiring further explanation, add a longer description below the title. This is optional but valuable for complex changes, and bullet points or short paragraphs can help with clarity.

Here's a sample commit message that demonstrates these conventions (first line is the title and the following are the description):

1JIRA-1234: Add Two-Factor Authentication to user login
2
3Enhanced security by adding two-factor authentication. Includes frontend and backend updates:
4
5- New 2FA modal on the login screen
6- Updated API endpoints to support token-based authentication
7- Adjusted user authentication logic in the backend service

Commit message do's and don'ts

By following the following do's and don'ts, your commit messages will be clear, concise, and helpful to your team and future maintainers.

Do's

1. Be specific: Clearly state what the commit changes. Instead of "Fix error," use "Fix null pointer exception in login validation."
2. Break down large changes: Make small, atomic commits focused on a single change or improvement. This keeps history clean and easy to track.
3. Use present tense: Write in the present tense, as if you're instructing the code to do something (e.g., "Add validation check," not "Added validation check").
4. Reference other commits when needed: If a commit is related to a previous one, refer to it by hash or issue number, providing context for reviewers.
5. Think about future readers: Consider that others (or even you) will be reading these messages months or years down the line. Make messages understandable even for someone unfamiliar with the current state of the project.
6. Use active voice: It's clearer and more direct. Instead of "Bug fixed by updating API", write "Fix API response bug".

Don'ts

1. Don't summarize multiple changes: Avoid combining unrelated changes in a single commit. Keep each commit focused.
2. Don't write empty commit messages: Never commit without a message, even for minor changes. A brief explanation is always better than nothing.
3. Don't be too vague: Messages like "Update code" or "Fix stuff" don't provide context. Always give enough detail to understand the change.
4. Don't write messages that depend on external context: Avoid relying on information only available elsewhere, like Slack chats or team notes (e.g. "Fixed what Svein said"). Ensure the commit message is self-contained.
5. Don't focus on what changed in detail: Use the code itself to show exactly what changed, and focus the message on the reason for the change.
6. Don't use humor or jokes: Messages should remain professional and focused. Humor may not translate well, especially for future readers.

Additional tips

Consider your teammates

A clear message should be understandable to your teammates and future developers.

Practice consistency

Following these guidelines consistently across your team will make your project's history more readable. A consistent format ensures everyone knows where to look for specific information.

Why I don't recommend Conventional Commits

While Conventional Commits can bring structure, they're not without drawbacks. Here are a few reasons why I'm not a fan of this format:

• Rigid structure: The strict syntax required by Conventional Commits (e.g., "feat: add login feature") can feel overly restrictive, especially for smaller teams or projects. It may discourage natural documentation in favor of adhering to a format.
• Steep learning curve for new developers: The Conventional Commits format requires developers to follow specific rules and prefixes. For new team members, this can be a barrier to contributing quickly, slowing down the onboarding process.
• Emphasis on style over substance: Conventional Commits can shift focus from writing meaningful messages to fitting a syntax. The forced categorization may lead to overly simplistic messages that overlook the real "why" behind changes.
• Increased maintenance: Adopting Conventional Commits often requires additional tooling or setup to enforce the format, adding to the maintenance load. This can be overkill, especially for small projects or agile teams where priorities shift quickly.

Conventional Commits have their place, but they can also hinder clarity and add unnecessary complexity. For many teams, a simpler and flexible approach to commit messages can be more effective.

Conclusion

Commit messages are a small but crucial part of the development process, enabling efficient collaboration, better project organisation, and smoother troubleshooting. By following these simple guidelines, you can create a reliable, readable, and traceable version history that benefits your whole team and future maintainers.