101 to Commit Message

So you are a young developer. You are close to or have already finished your studies and decided to get your first job. You will start working in a team - that's the main difference between the job which you will be paid for and projects made at home or ones for educational purposes. A team will consist of two or probably more people (we at Monterail have teams with size of 2 up to 10 people). Regardless of the company that you will join and the programming language and tool set you will learn, you will need to become familiar with the word teamwork and its meaning.

And you will definitely start sharing your work by revision control system like git or any other - it doesn't matter. What matters is that you have to learn some common rules about how to do it right.

Commit message done bad

Please read the code below and try to guess what it does. Even if you are not familiar with the ruby language, it shouldn't be hard to complete this exercise.

class SessionController < Devise::SessionController
  def new
    if flash[:alert] == unauthenticated_message
      flash.delete(:alert) unless requested_protected_page?
    end
    super
  end

  private

  def requested_protected_page?
    session[:user_return_to] != root_path
  end

  def unauthenticated_message
    I18n.t("devise.failure.unauthenticated")
  end
end

Ready? Was it hard? Now let's see the commit message sent by the developer who shared this piece of work with you.

[AUTH-391] Override Devise::SessionController

Remove flash alert if user is requesting root path

Do you feel like someone is reading the code for you?

What is missing here? An explanation why this code does what it does. Are you able to guess that from the commit message? Me neither.

Why do you need coding style guides?

The answer is simple - to make your life easier.

Style guides allow us to not waste time wondering about unimportant stuff while coding. Should I put a space before the bracket? Should I enter a new line after? Dozens of questions to respond to during every minute of a coding session. Style guides comes to the rescue and remove the burden of worrying about that from your shoulders - you just need to learn it once and apply the correct solution to the encountered problem.

It is also part of your programming driving license - a set of rules about how to behave on the road to not hurt yourself and your colleagues. Without that, you shouldn't be allowed to enter traffic.

Good commit message rules

Here I can just paste one link - to the good old article from Tim Pope: A Note About Git Commit Message. It mostly describes everything that you need to know. If that's not enough, I can also recommend How to Write a Git Commit Message by Chris Beams.

But I won't be that lazy and I will describe the rules to you as briefly as I can.

In essence, a commit message should be divided into three parts:

• short summary in the first line
• empty line
• more details

The first line should tell others what you did, it should be Capitalized and only 50 characters long. It's like a title, so you can easily display a list of commits and find the one that you are interested in. Our preference is to prefix the first line with issue number in square brackets, like in an example shown before [AUTH-391], but this is not a general rule.

The empty line gives visual separation between the commit title and the full description.

Then you have a details section. Focus on the description - why you did what you did and why you did that it in such way - any specific reasoning that is not obvious from the code should be put here. If there are a lot of changes it is also a good idea to briefly list them. Finally, keep the lines shorter than 72 characters.

In both the summary and details sections use the imperative style, third person perspective and present tense. Now you won't need to wonder how to write your message.

And that's it. It's not rocket science, so do yourself and your colleagues a favor and read the linked articles and start following these rules today.

Thank you.