Writing Better Commit Messages: A Guide for Beginners

Wondering why you need to write commit messages or what exactly a good commit message looks like? Commit messages might seem trivial, especially when you’re in the middle of coding. 

But, their importance becomes clear when tracing back through a project’s history, understanding changes, or collaborating with a team. In this post, we’ll delve into the significance of commit messages, and provide beginners with a simple framework to get started.

Why Commit Messages Matter

1. Traceability

Commit messages help in tracing why a specific change was made, providing a clear record for future reference.

2. Documentation

Think of them as a continuous stream of documentation. They assist both future developers and your future self in understanding the evolution of the project.

3. Collaboration

When working with a team, clear commit messages ensure that everyone is on the same page.

4. Code Review Efficiency

With clear commit messages, code reviews become a breeze, enabling reviewers to understand the context of changes swiftly.

The Anatomy of an Effective Commit Message

For a commit message to be truly effective, it should have:

1. Short, Descriptive Title

This should be 50 characters or less and provide a concise description of the main change.

2. Detailed Description (Optional)

For more complex changes, a detailed description can further explain the context and reasoning behind the commit. Aim to keep each line under 72 characters.

3. Issue or Ticket Number (Optional)

If you’re using an issue tracker, this is where you reference the issue or ticket number.

Practical example

Imagine you’re working on a project where a user reported an issue: they can’t reset their password due to an error in the email sending module. You’ve identified the bug and made the necessary code changes to fix it.

Here’s how you’d craft the commit message:

1. Short, Descriptive Title

Fix email sending bug in password reset

This title is concise and immediately informs a reader about the main change in the commit.

2. Detailed Description (Optional)

The password reset module relies on the email sending functionality 

to dispatch reset links. A mismatch in the parameter order in the 

sendEmail function was causing it to fail. This commit corrects 

the parameter order and adds additional error logging to catch 

similar issues in the future.

This description explains the context (why this change was necessary) and the reasoning behind the fix (what was done to address the issue). Each line is kept under 72 characters for better readability, especially in command-line tools.

3. Issue or Ticket Number (Optional)

`Related to issue #456`

If your project uses an issue tracker (like GitHub Issues or JIRA), referencing the specific issue or ticket number provides an easy way for team members to find additional context or discussion about the problem.

Combining all these components, the complete commit message would look like:

Fix email sending bug in password reset

The password reset module relies on the email sending functionality 

to dispatch reset links. A mismatch in the parameter order in the 

sendEmail function was causing it to fail. This commit corrects 

the parameter order and adds additional error logging to catch 

similar issues in the future.

Related to issue #456

This commit message provides a clear and comprehensive understanding of the change, making it easier for any team member (or your future self) to understand the reasoning behind this commit.

A Simple Framework for Crafting Commit Messages

Here are some straightforward guidelines for beginners:

1. Use the Imperative Mood

Starting with verbs like “Add”, “Fix”, “Change”, or “Remove” sets a clear action tone.

2. Be Explicit

State what you did and where you did it. Specificity is key.

3. Avoid Vague Descriptions

Steer clear of generic phrases that don’t provide clear insight.

4. Bullet Points for Multiple Changes

For commits with multiple changes, bullet points can provide a clear and organized description.

5. Link Relevant Resources

If a change is based on a specific resource, link to it.

Commit Message Examples to Get You Started

• Add user registration feature
• Fix bug causing app crash on login
• Update README with setup instructions
• Remove deprecated API endpoints`
• Refactor payment processing module for clarity

Templates for creating good commit messages

Here’s a comprehensive template of commit messages that caters to various scenarios that you may encounter. If you are a beginner then you can use this as a reference to ensure that your commit messages are clear and descriptive:

New Features:

• Add [specific feature name]
  • Example: Add user registration feature

Bug Fixes:

• Fix [specific bug/source of the error]
  • Example: Fix bug causing app crash on login

• Resolve issue #[issue number]
  • Example: Resolve issue #123 related to payment gateway

Documentation:

• Update [specific file or section] with [specific change]
  • Example: Update README with setup instructions

• Document [specific feature or function]
  • Example: Document the calculateTotal function

Code Refactoring:

• Refactor [specific module or function] for [specific reason]
  • Example: Refactor payment processing module for clarity

Removing Code/Files:

• Remove [specific feature, function, file]
  • Example: Remove deprecated API endpoints

Performance Improvements:

• Optimize [specific function or feature] for [specific improvement]
  • Example: Optimize image loading for faster page rendering

Dependency Updates:

• Upgrade [dependency name] to [version]
  • Example: Upgrade lodash to v4.17.20

• Downgrade [dependency name] to [version] due to [specific reason]
  • Example: Downgrade react to v16.13.0 due to compatibility issues

Testing:

• Add tests for [specific feature or function]
  • Example: Add tests for user authentication flow

• Update tests for [specific change or feature]
  • Example: Update tests to reflect new login behavior

Style or Formatting:

• Format [specific file or module] with [tool or style guide]
  • Example: Format UserComponent with Prettier

Continuous Integration/Deployment:

• Configure [CI/CD tool] for [specific task]
  • Example: Configure Travis CI for automated testing

Reverting Changes:

• Revert “[previous commit message]” due to [specific reason]
  • Example: Revert “Add new login feature” due to security concerns

Miscellaneous:

• Initialize project with [specific tools or frameworks]
  • Example: Initialize project with Create React App

• Merge branch ‘[branch name]’
  • Example: Merge branch ‘feature-new-login’

Pro Tips for Mastery

1. Embrace Atomic Commits

Focus on one task, feature, or fix per commit.

2. Commit Often

Regular commits ensure that changes are fresh in your mind, making it easier to write accurate descriptions.