November 25, 2015
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.
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.
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.
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:
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.