Light of a Thousand Commits

In different parts of your career as a Software Engineer, a lot of good ideas will appear and vanish with ease. What you remember right now, you will forget after couple hours. Same happens with our code, and you can’t do anything about it. Or wait… maybe you can?

Lets go several years back and try to remember how we have used to write code. I am sure that I am not the only one who was editing code on the production server via FTP. Back then I was thinking only about the result that I will see. I never thought that someone will use this piece of sh splendid code after many years. Actually no one did, except myself.

When you look at your 5+ year old photos you feel nostalgic inside. If you are a Software Developer you will have the same feeling looking at your old code. And you might even ask yourself — why I wrote it like this? Some of us will think — “Oh my, this code is much better and simpler than I write now”. But the most frustrating question is — why the hell I did what I did? Current me would tell “If you’d know about Git back then, things might be so simpler”… is it true?

Can anyone tell me that VCS is the best thing happened to him? And working with many teams it will auto–magically solve problems with work description? Years ago there where no Github — no place where Developers can show off in front of other Developers. Back then to show your mad development skills you have to show a well written code. Now its different. Instead of code you can show how well structured your commit messages are and you will be a national hero.

Open-source

Elasticsearch commit messages

Open-source is great. It raised a lot of magnificent developers. They get their skills by overlooking other software code and contributing to it. Lets skip the code part and talk straight about commit messages.

Commit message is the single source of truth that describes why all these files where touched

A lot of people measure quality of code by looking at commit messages. If they are understandable and well written — developers are seniors. Otherwise juniors. In most cases this is the end of the story. Developers want to read something and the best sellers are always free. Grab cup of coffee or tea and go through popular open-source projects commit messages.

We all know about this great article by Chris Beams about commit message — http://chris.beams.io/posts/git-com....

This great seven rules helped to raise a bar of commit messages in a lot of projects. Here and there you will hear and see almost all the following rules implemented.

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

It looks promising, but how many of you can show me such detailed commit descriptions? Isn’t it like all discussion about implementation happens in Tasks?

Some tasks are better than others. I think everyone will agree that a some changes to the initial task requirements may appear in the comments. How many of you will replicate description of each change to the commit message?

The one rule, that is missing from the “The seven rules of a great git commit message” relates to the Ticket number you are currently working on. And this rule is the most important among others.

Always start your commit message with a ticket number you are currently working on

You can start to argue with it straight away, but lets look at the Business Projects development. By Business Project I mean anything that is not driven by communities in Open Source projects.

Business Project Development

Product Owner with other Business people will come up with a great idea. They will try their best to describe it, to come up with a design and requirements. They will do the detailed description in the story, some of them will attach Wiki page with even more detailed description and use-cases. It even might be a small puzzle in the the big epic. In the end of this process, you as a developer will get the story with number ZCR-1. You will transform this piece of an idea into a great realisation. And the main question is what you will leave behind?

  1. Great code and single commit message: “Great feature implementation”
  2. Great code and 22 commit messages: “Added models”, “Added services”, “Added controllers”, “Added tests” ….
  3. Great code and 51 commit message (after someone reviewed your PR): “Added models”, “Added services”, “Added controllers”, “Added tests”, …., “Fixed service implementation”, “Fixed tests”, “Fixed Typo”, “Fixed Typo”, “.”
  4. Great code and 51 commit message. It started as (2) with 22 commit messages, it continued to grow to 51 commit message. In the end you’ve got 10 more commit messages starting with “Fix”. You did rebase, squash and ended up with single commit message like in (1).
Every developer in his career should do 3 things: Build a house, plant a tree, and rebase ton of commit into single one because “sh*t, I can’t handle it anymore”

What if I tell you, that “Great feature implementation” commit has the same level of uselessness as “Created service for tax calculation” and similar? After 6 months when maniac developer with chainsaw will check your code, he won’t be happy. Good for you, that you have already left the company.

All of this commits do not have a context. Its impossible to get from the code to the root of a problem, to the Story and Business people description & discussion. If you are lucky enough, previous developer will link a branch where he wrote the code in the Ticket. This gives you at least one possibility to have the full path of the story development — from the initial specification with description to the code implementation.

What if you got a new project and you have only code? How to find out why specific line was written? If you care about the code, you would like to know the reasoning behind such implementation. And what might be the best place if not Ticket description & comments? The question which bothers you right now — “How I can get from code to the Ticket description?”

Draw a line between Code and Requirements

On the screenshot we see, that all 7 rules where followed. Except the missing part — the 8th rule. Its totally impossible to get from this code to the Ticket number. How easy it might be, if specify first line of this great subject as

#10596 Introduce routing service

As we know that the context of this project is in Github, we can easily find it just by specifying this ID in the url. We end up in the ticket https://github.com/emberjs/ember.js/pull/10596 with a quite deep discussion on what was done and why.

If this would be a Jira project, subject might look like this

EMBER-10596 Introduce routing service

To go even deeper, name your branches with the ticket number pre-defined:

ember-10596-introduce-routing-service

You will see the benefits of such naming when you will start to work with other people. It will give you an easy overview what tickets are currently in work and who is doing them, just by looking at remote branches.

Key Takeaway

Think about requirements and the code as a family. Family with a strong bond. Expose your requirements down to the code and your code up to the requirements. As a parents share their experience with a child and a child who bring his knowledge back to parents.

Remember — earlier you will start to prepend ticket numbers to your commit messages less frustration and questions your code will rise in the long run from other developers.