Best Practices for Writing Commit Messages and Code Comments

Every line of code you write solves a problem.But what if someone else has to understand, fix, or build on that code tomorrow, or even months from now? That’s where your commit messages and code comments become silent allies. They don’t just document your work, they tell the story behind it. They capture the why, not just the what.They transform a code-base from a pile of logic into a living, collaborative space.

In this guide, we’ll walk through simple, practical tips to help you write commit messages that matter and comments that make a difference, so your future self (and your team) will thank you.

Let’s make your code not just functional, but unforgettable.

Writing Good Commit Messages

Why Commit Messages Matter

Commit messages are documentation. They:
a. Explain the intention behind code changes.
b. Help future developers (including yourself) understand the history
c. Make debugging and code reviews easier
d. Improve collaboration and traceability

Format

Use this structure:
<type>: <short summary>
[optional body for context]

Common Commit Types

feat Used when Adding a new feature
fix Used when Fixing a bug
refactor Used when Restructuring code without changing behavior
docs Used when Updating documentation
style Used when Code formatting (indentation, spacing)
test Used when Adding or fixing tests
chore Used for Misc tasks like build, CI, config

Writing the Summary

a. Be concise and start with a verb:

    fix: handle null user on login
    feat: add dark mode toggle

Limit to 50 characters if possible

b. Use present tense (as if describing what this commit does)
Example Messages

    feat: implement user login endpoint
    Added JWT-based authentication with login and token generation.

    fix: correct typo in signup form validation error
    refactor: extract database logic into separate package

Writing Clear Code Comments

Why Comment?

a. Explain why, not just what

b. Clarify complex logic, not the obvious

c. Help future readers maintain or extend the code

Commenting Best Practices

Avoid obvious comments

     ❌ i++ // increment i
     ✅ i++ // move to the next user in the list

Use comments to explain “why”, not “what”

     ❌ // fetch user
     ✅ // Fetch user so we can prefill the edit form

Document assumptions, edge cases, and decisions

     // We retry 3 times to handle transient network failures
     for i := 0; i < 3; i++ {
     ...
     }

Prefer self-explanatory code over excessive comments

• Rename variables or functions if a comment feels necessary

   // Bad
   let x = 10; // maximum retries
   // Better
   let maxRetries = 10;
  

Use TODO/FIXME tags sparingly and consistently

     # TODO: Refactor this to async in next release

What to Avoid

a. Vague commit messages like changes, update, or fix bug
b. Over-commenting every line
c. Outdated comments - update or remove them as code changes
d. Jokes or sarcasm in comments (yes, it happens)

Final Tips

a. Use version control tools (git log, git blame) as communication history
b. Treat your commit history like documentation
c. Imagine someone else reading your code months later, what would they need?

Conclusion

Great code is more than just working code, it's communicative, thoughtful, and human-friendly. Every commit message you write is a window into your decision-making. Every comment you leave is a helping hand to your future self or another developer.

So don’t just write code, tell the story behind it. Be the kind of developer others thank when digging through version history or deciphering a complex logic flow.

• Let your commits document your journey.
• Let your comments guide the reader through your thinking.
• And let your code-base be one that’s not only powerful, but understandable, maintainable, and admired.

Now go write like someone will read it, because they will.