Explore why simply following conventional commits isn't enough to write good commit messages, and introduce key thinking strategies to improve your development process and naturally create meaningful commits.

A quick search on the internet will reveal a plethora of articles teaching you how to write commit messages. 90% of these articles tell you to use conventional commits. However, a considerable number of developers still struggle with this. They know they should follow these conventions, but they find it difficult to apply them in practice. Every time they commit code, they agonize over whether to write "refactor" or "chore". I've even seen projects where the commit message list consists entirely of the same message: "feat: add page", because writing commit messages was too challenging for them, and they simply gave up.

It's too early to talk about conventional commits

I'm not saying that conventional commits are bad. They have many well-known benefits:

• They provide a unified format, making commit messages more standardized
• They are easy for automated tools to parse, enabling automatic changelog generation
• They help team members understand the purpose and scope of code changes
• They allow for quick identification of different types of code changes

However, when a developer is still struggling to write good commit messages even after using conventional commits, throwing an article at them about how to use conventional commits, teaching them what feat type means, what fix type means, is actually meaningless. It's like giving an advanced cookbook to someone who doesn't know how to cook, without teaching them how to use basic ingredients and utensils. Yet, such articles are everywhere on the internet. Little do they know, conventional commits can only truly be effective when developers have clear thinking and the ability to divide tasks precisely.

So, conventional commits aren't bad, but before we get to that, we need to establish the right development mindset and use scientific developer thinking to do things.

Key thinking for writing good commit messages

Code changes should do one thing at a time

In software development, "do one thing at a time" is an important principle. This applies not only to writing code but also to committing code. When we focus on one specific task or change at a time, our code becomes clearer and our intentions more explicit. This method not only improves code readability but also greatly simplifies the code review process. Reviewers can more easily understand and verify the purpose of each change.

Moreover, this method provides convenience for potential code rollbacks. If problems occur, we can more easily locate and revert specific changes without affecting other unrelated parts. Most importantly, when each change does only one thing, the commit message describing this change naturally becomes more precise and meaningful.

In practice, this means we need to clearly define the task to be completed before we start coding. After completing a task, we should immediately commit the code, rather than waiting until multiple tasks are completed before committing together. If we discover other areas that need modification while completing the current task, the best approach is to note them down and handle them separately after completing the current task. For example, when you're implementing a feature and discover some existing bugs, what you should do is not fix the bug right away along with your new feature code, but rather implement the feature first, then fix the bug you discovered in another commit, or fix the bug first and then commit the feature.

Commit messages actually exist before writing code

Many developers only start thinking about how to write commit messages after completing the code, but in reality, commit messages should exist before we start coding. This is because commit messages essentially reflect the steps we take to complete a task. In other words, they are our todo items.

When we start a task, we should first think about what specific steps are needed to complete this task. These steps are our todo list, and at the same time, they are our future commit messages. With this todo list, each of our code changes has a purpose, keeping us focused while coding and preventing us from deviating from the task.

More importantly, this method can significantly improve our efficiency. When we complete a step, the corresponding commit message is already prepared, and we can use it directly, reducing the time spent on thinking about how to describe the change. At the same time, because these commit messages are completed when we have a comprehensive understanding of the task, they are usually of higher quality and more informative.

Suppose you need to implement a new user registration feature. You might plan your task steps like this:

1. Refactor the existing form component to make it more generic and reusable
2. Create a user registration form
3. Implement API integration for user registration
4. Add unit tests for the user registration feature
5. Update documentation for the user registration feature

The commit messages corresponding to these task steps might be as follows:

1. refactor: enhance existing form component for reusability
2. feat: create user registration form
3. feat: implement user registration API integration
4. test: add unit tests for user registration
5. docs: update documentation for user registration feature

In this way, you have clear task steps and corresponding concise commit messages before you start coding. These commit messages are actually your todo list, guiding you through the entire process of implementing the feature.

As you complete each step, you can use the corresponding commit message to commit your code. This not only helps you better organize and execute tasks, but also ensures that each commit focuses on a specific step, making the entire development process clearer and more manageable. If you need to slightly adjust the commit message during actual coding, you can make minor modifications to more accurately describe the actual changes.

Conventional commits become a natural choice

When we develop the right development mindset, using conventional Commits becomes natural. At this stage, you'll find that choosing the appropriate type prefix (such as feat, fix, refactor, etc.) becomes effortless because your commit messages already clearly reflect your task steps.

If you want to learn more about how to use conventional commits, there are many excellent articles available online. But remember, these standards can only truly be effective when built on the foundation of the right development mindset.

Conclusion

Writing good commit messages is not just about following a certain format. It requires us to maintain clear thinking during the development process, clarify the purpose of each change, and consider how to describe our work before we start coding.

Conventional commits is indeed a useful tool, but it can only exert its maximum effect when combined with the right development mindset. By practicing the two principles of "do one thing at a time" and "think about commit messages in advance", we can not only improve the quality of commit messages but also enhance overall development efficiency and code quality.

I hope this article helps you rethink your development process and encourages you to try these methods. Remember, good development habits take time to cultivate, but once formed, they will greatly improve your work efficiency and code quality.

Try Logto Cloud for free