Why Commit Messages Matter

Good commit messages are essential for maintaining clarity and collaboration in projects. As your project scales or multiple contributors work together, precise and consistent commit messages help developers understand changes faster, troubleshoot issues, and streamline code reviews.

Fun Fact: According to a study at Microsoft, new developers often spend between 60% and 80% of their time understanding code when joining a project. As they become more familiar with the codebase, this percentage decreases, but it underscores the importance of clear commit messages.

The Golden Rules of Commit Messages

1. Start with an Informative Title

• Rule: The title should summarize the change in 50 characters or fewer, include the affected component, and be written in the imperative mood (e.g., "Fix" rather than "Fixed").
• Example: Good: UI: Fix alignment issue in settings menu Bad: Fix issue

Including the affected component makes it easier for readers to understand the context at a glance.

2. Use a Brief Overview in the Body

• Rule: Explain why the change was necessary and how it fixes the problem. If applicable, reference the issue ID (e.g., #56255) or relevant documentation.
• Example:This commit removes extra spaces found in the Learn HTML by Building a Cat Photo App - Step 29. It resolves issue #56255 by following HTML formatting guidelines.

3. Check the Style of Commits in Your Project

• Rule: Review existing commit messages in the project to ensure you’re following the same format. Check if the project has a contributing guide with specific instructions for commit messages. Use tools like git log --oneline to observe recent commit styles.
• Tip: Following the project's preferred style maintains consistency and helps during code reviews.

4. Follow Any Standard Documentation

• Rule: Many large repositories (e.g., Linux Kernel, Kubernetes) follow strict guidelines for commit messages. Check the project's contributing guides or coding style documentation.
• Example from the Linux Kernel Documentation: Titles should:
  • Be written in the imperative mood (e.g., "Fix bug" rather than "Fixed bug").
  • Include the affected subsystem or component (e.g., net: Fix checksum issues for TCP packets).
  • Be no longer than 50 characters. Read more in the Linux Kernel Documentation.

5. Minimal and Clean

• Rule: Commit titles and messages should be concise and informative. Avoid unnecessary words or overly long explanations. Focus on the essentials to maintain clarity.
• Example: Good: Refactor DB connection logic Bad: Refactor and clean up the way that the DB connection logic works