Writing Good Commit Messages
Commit messages are critical for anyone reviewing your code. Most well-run open source projects actually have strict requirements for how commit messages are structured. For instance, here are the official Go guidelines on commit message structure. But beyond structure, what content should you include in your commit message?
As with all writing it’s important to understand who your audience is. With commit messages, your audience is reviewers and future developers. These two classes of people share one common desire: to know why a change is being made. Any one can observe the code that you’re changing and discern its effects. What is not obvious is why such a change is desirable.
Your messages don’t have to be long. But they MUST include why the change is being made. They MAY also contain information about what is being changed for clarification purposes, but the why is more important. If you’re ever at a loss for what to put in your diff description, try to come up with at least one sentence that describes why the change is necessary/advantageous/makes the code base better. Let’s look at a couple examples:
Bad Description
Imagine you have a change that is deleting a bunch of code from your code base. You use the following commit message:
This change removes feature X.
Well yea, I could probably have figured that out by the fact you’re deleting a bunch of code. Imagine this change needs review from someone on another team. That person probably considers feature X important, so they’re likely to have some trepidation with regards to removing it. Or imagine an engineer who got hired a year after this change was made and their PM is now asking to add feature X back into the code base. They wouldn’t really have much information to go on here. Should they add back feature X? This commit message certainly won’t help them make a decision.
Good Description
Now imagine you’ve made the same change as above, but used this as your commit message:
This change removes feature X because of a performance regression. Details on this regression can be found in task T12345.
Ah, perfect. There was a performance regression. That’s certainly a good reason to remove a feature. If I’m an engineer on a different team and I see that message, I’m much more likely to accept your change. This message even goes one step further by letting me know where I can get further details should I be interested. Our imaginary future engineer from above would also be able to go back to their PM and say there’s a performance regression that will need to be addressed first before the feature can be added back. And they’ll have the exact task!
Closing Thoughts
The more distributed your company is, the more important all of this is. At Uber, we have a highly distributed organization with many engineers in different locations and different time zones. That means we need to lean hard on communication skills. All the standard good writing practices also apply here. Use complete sentences and passible grammar.
Communication (specifically/especially writing) is a core competency for all engineers. Developing this skill is well worth the time investment and will pay large dividends over the course of your career.
