Commit your code they said

Posted by Łukasz on 07 Nov 2018.

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):

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

Make it readable fool!

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

or this one?

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:

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.

References


Tell me what you think!