Whenever you’re presenting code to other people, through a pushed commit or a review request, it’s important to ensure that your change’s description sufficiently communicates its purpose. Another person should, without ever seeing the code or reading an associated bug report, have a clear understanding of the problem you are solving and how you are solving it.
Writing good change descriptions is first and foremost a question of good writing. Make sure that everything you write uses full sentences with proper spelling and capitalization.
A good description of a commit or a review request starts in two parts: A clear summary of the purpose of the change, and a detailed description explaining the why/how of the change.
Review requests have one further requirement, which is to explain the testing that was done for the change. This should provide a reader with enough information to feel confident that your change has been thoroughly tested.
Let’s go into each of these.
A summary should be clear and concise, not cryptic. It should accurately sum up the purpose of the change in under 80 characters (and should not wrap). It should also be in sentence casing, with a trailing period.
It should not include details that could otherwise be found in the description such as bug numbers or filenames, with very few exceptions.
When drafting a summary, try to figure out what you would verbally say to someone if you had one sentence to explain your change.