Commit your code they said

Created on: 2016.08.27

There are so many situations when you get access to a new repository on GitHub, Bitbucket or any other place. And what are you welcomed with? If the repo isn’t managed corectly, you usually get crappy messages that don’t say you a thing. Today I will try to show you, from my experience, what is the best course of action when writing commit messages, so that everyone understands them (and by everyone I mean you as well, try going back to a project after one year… this can be a really bad experience).

But before we begin, let’s see what bad commit messages look like. This is sample stuff I came across lately while browsing public repositories or checking new programmers for work (don’t try this at… anywhere actually):

• “Everything works, but nope”
• “Dick” (this seems to be quite common, why is beyond my comprehension)
• “No one will read this anyway”
• “I made changes”
• “It’s a trap” (my inner nerd giggled here a bit)

Make it readable fool!

So what can we do to actually make our work and others simpler and without problems?

Let’s do a little experiment. Which commit message would you prefer to read?

I implemented the method FeedChicken(chickenId, feedId) in the ChickenFarm.cs to allow user chickens eat specific feeds in order to survive the harsh enviroments of Chicken Farm World

Add method to feed chickens

While the first one tells you exactly what has been done, try going through hundreds of such commits in search of something you actually need. You should keep the messages short, easy to read and telling precisely what the commit is about. All the internet or book sources will tell you about the 50/72 rule (which is really handy if you need to write something more about the commit than just the summary). Look at this short description taken from Tim Pope’s Blog:

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.

Write your commit message in the imperative: “Fix bug” and not “Fixed bug” or “Fixes bug.” This convention matches up with commit messages generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

– Bullet points are okay, too – Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here

– Use a hanging indent

Reference the system

Most projects you are working on are managed by project managements systems like Jira, Trello or whatever your PM chooses. One of the key features presented on assigned tasks is the task reference ID. I would ask all my programmers to add a reference to the task at the start of each commit. I didn’t see this anywhere on the internet, but I found it really helpful when dealing with junior programmers or systems with lots of people involved. And this is how such a commit would look like:

[CFW-1] Release ChickenCoop 1.0.0

This becomes really helpful when you have tasks that don’t require branching or just want to see what is worked on and how is that achieved, especially if you need to go through with code reviews for beginner developers.

Use keywords

Keywords at the start of every commit make it easier to read what were you actually doing. Try using those keywords instead of verbs:

• Add (e.g. “add chicken digestion system”)
• Remove (e.g. “remove deprecated chicken”)
• Refactor (e.g. “refactor chicken brain”)
• Update (e.g. “update chicken skynet data”)
• Merge (e.g. “merge chicken/coop branch”)
• Release (e.g. “release the chickens”)
• Fix (e.g. “fix chicken egg production”)

Of course you can use your own keywords that will be useful for your project, but I think you get the general idea. I gave you the most used ones, for general purposes.