Best Practices for Commit Messages: A Guide for Developers

Previously in this course, we learned how to track tasks using GitHub Issues for Task Tracking. While issues describe what we intend to do, your commit messages serve as the permanent record of how and why we implemented those changes.

As your project grows, your commit history becomes your primary tool for debugging and auditing. A cryptic "fixed stuff" message is a liability; a clear, descriptive message is an asset.

The Power of the Imperative Mood

When you write a commit message, you are effectively completing this sentence: "If applied, this commit will..."

This is the imperative mood. It’s the standard convention for Git, mirroring the way the git merge or git revert commands report their own actions. By starting with a verb in the command form, your history reads like a concise log of changes rather than a diary of what you did.

Examples:

• Bad: "Added a new validation function" (Past tense)
• Good: "Add validation for user email input" (Imperative)
• Bad: "Fixed the bug in the login page" (Passive)
• Good: "Fix crash on login when password is empty" (Imperative)

Describing the 'Why' Behind Changes

A common mistake beginners make is focusing entirely on the what—the code diff itself. Git already knows what changed; you can see the diff with Checking Status and Differences.

Your commit message should explain the motivation. Why did you choose this implementation over another? What issue are you resolving?

The Standard Commit Structure

A professional commit message should follow a specific structure:

1. Subject Line (Max 50 characters): A short summary in the imperative mood.
2. Blank Line: Essential for separating the subject from the body.
3. Body (Max 72 characters per line): Detailed explanation of the why, context, and any trade-offs made.

Worked Example

Imagine you are working on your collaborative project. You’ve just optimized a database query. Instead of a generic message, use this structure:

TEXT
Optimize search query for user profiles

The previous implementation used a sequential scan, which caused 
latency spikes as the database grew. This change adds a GIN index
to the username column, reducing lookup time by 80%.

Closes #12

By referencing the issue number (Closes #12), you link your documentation directly to the task tracker, creating a seamless audit trail.

Hands-on Exercise

For your current project, identify a recent change you made. Perform the following steps:

1. Open your terminal and run git log to view your last few commits.
2. If you have a vague message like "update code," use git commit --amend (if it hasn't been pushed yet) to rewrite it.
3. Rewrite the message using the imperative mood and add a brief body explaining why you made that change.
4. Run git log again to see how much more readable your history has become.

Common Pitfalls

• The "And" Trap: If you find yourself using the word "and" in your commit subject, you are likely doing too much. Split the work into two separate commits.
• Neglecting the Context: Always assume the person reading the commit six months from now—which might be you—has no memory of the current project state.
• Too Long/Too Short: Keep the subject concise but descriptive. Don't leave the body blank if the change involves complex logic or architectural decisions.

FAQ

Why does the subject length matter? Tools like GitHub and Git command-line interfaces truncate messages longer than 50-70 characters. Keeping the subject short ensures it remains readable in list views.

Is it okay to use past tense? While some teams allow it, the imperative mood is the industry standard for Git. It keeps the history consistent and clean.

Does this count as documentation? Absolutely. Just as you maintain API Documentation Basics, your commit log is live documentation that explains the evolution of your software's logic.

Recap

Clear commit messages are a hallmark of a professional developer. By using the imperative mood and focusing on the "why," you provide critical context for your team. This practice turns your repository into a self-documenting project that is easier to maintain, debug, and scale over time.

Up next: We will look at how to clean up a messy history by learning about squashing commits.