Commit Verbs 101: why I like to use this and why you should also like it.

A little about communication in projects.

NOTE: If you don’t know about any version control system, please read more about GIT, Mercurial or Subversion (I prefer the first), and then continue to read this article.

When we realize that our software developer job goes far beyond a simple isolated coding work and becomes connected to an ecosystem of developers, it’s time to know how to communicate well in this ecosystem. GitHub users know what I’m saying.

If you work in projects with a new employees constantly, or collaborate in projects around the world, is important to keep communication conventions. And even if you work on a project alone, double or with a small team, the conventions are essential too.

Why use conventions is easier for everyone

If the team has enhanced communication, this will win somehow. For this, it is necessary to eliminate any noise. One way for this, is use conventions to communicate what we will or we are doing.

In addition to being clear and objective, the main feature of effective communication are conventions. This ensures that everyone on the team share the same meaning. For communication to be effective, is necessary to establish a common communication environment for all. Otherwise, we run the risk of make our confused communication.

In the commit logs, specifically the conventions will be key. At some point you will need to understand what was done, either to fix a bug, or even go back to an earlier stage. By using conventions, will be much easier to see what you did and to what extent to return.

Using conventions and specific verbs to your commit messages, you are helping yourself and others. Not only in public projects, and within your own team, but above all to yourself.

Conventions in commit messages

Common verbs will help you to keep a efficient communication. So it’s important to establish and agree on some verbs. I like these:

- Add some feature
- Remove class whatever
- Update dependency x
- Refactor function y
- Fix crazy bug

The common verbs are in bold. It’s simple and very useful. Each verb represent a single change in your code. You should always use them as a single prefix, and never use two in a single commit, e.g:

[bad] - Add some feature and Fix crazy bug 

Always use the verbs in Imperative Present tense. Don’t use Past or Present Continuous tenses for commits. See this guideline from GIT about this.

[good] - Add some feature
[bad]  - Adding some feature
[bad]  - Added some feature

In aditional you should consider to using GitHub, especially because a feature called: Issues. With issues you can extend the explanation of your commits.

With Issues you can increases well your commit message with a refer, e.g:

- Refactor function y. #1

In above commit, the Issue is referenced and appears as in the picture below:

A example of Github Issue.

With this you can know why the commit was made. Note that above is an open Issue, and you can close issues from a commit message, with a verb in your commit message.

- Fix crazy bug. Closes #2

See the picture below:

A example of closed Github Issue.

Now you have good reasons

The commit verbs help us and your team to keep projects clean and organized. If you have not used any of this, you consider to start to use now.

You have any suggestion? Feel free for comment and present your ideia.