Writing and Committing Code in GitHub: Writing a Good Commit Message

What should you write in a commit message? What makes a good commit message?

A Git commit should contain a logical and cohesive change or set of changes. The message should describe that change in clear terms so that anyone who reads the message later understands what changed in the commit.

The audience for the commit message are current and future collaborators on the project. Those collaborators may include yourself in the future. Someday you may be tracking down a bug and want to understand why you made some change. You’ll thank past-you for writing a well-written commit message that answers that question. So write clear commit messages and be nice to future-you.

If you find that you have trouble describing a commit, it may be that the commit contains too many changes. In writing code, we often note that well written func­tions do one thing and do it well. Similarly, a commit should represent one change to the system. The commit message describes the change and why it’s being made.

A good commit message should also follow a specific structure. In general, a com­mit message has two parts:

» The summary should be short (50 characters or less) and in the imperative present tense. For example, instead of writing “I added a method to Frobnicate widgets,” write “Add method that Frobnicates widgets.”

» The description provides detailed explanatory text, if needed. Not every change requires explanatory text. For example, if you rename a function, a commit message with just a summary of “Rename Frobnicate to Bublecate” may suffice. You should wrap the description text at 72 characters. This ensures it looks good when displayed in the terminal as part of the output from the git log command.

By convention, a new line character separates the summary from the description.

Here’s an example commit message written by one of the authors in an open source project https://git.io/fhZ5a:

Avoid potential race condition

 

In theory, if “ClearFormCache” is called after we

check ‘contains’ but before we execute the ‘return’

line, we could get an exception here.

 

If we’re concerned about performance here, we could

consider switching to the ConcurrentDictionary.

There’re a few conventions you can use within a Git commit message that Git will ignore, but GitHub will recognize. For example, you can specify that a commit resolves a specific issue with something like “fixes #123” where 123 is the issue number. When a commit with this pattern is pushed to GitHub, the issue number is linked to the issue. And when the branch that contains that commit is merged into the default branch of the repository (typically master), GitHub closes the referenced issue. That’s pretty handy!

You can also use emojis in a commit message. For example, one pattern some teams use is to indicate that a commit contains only cosmetic changes by prefac­ing it with : art:. When that commit is rendered on GitHub.com, GitHub renders the emoji. You can see this in action in Figure 7-2 which shows a list of commits from the GitHub for Visual Studio open source project https://git.io/fhnDu.

Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.

Leave a Reply

Your email address will not be published. Required fields are marked *