Geekly Articles each Day
📜 ⬆️ ⬇️

Commit Naming Style

the Octobi Wan Catnobi

There are a lot of information about many development points. How to write comments, how to name classes, methods, what patterns to use, etc. etc. But there is one area in which many people don’t even think that something can be improved is the writing of commits.

Why is it even needed? To save time and nerves, nothing more and nothing less. We will discuss this a little later, but for now we will look at what commits are called.

General style


If you go through the same commits with GitHub, you can see a fairly extensive number of commits to write. The main recommendations for writing are:
')
What to do + for which entity + details (optional)

Try to find a uniform style for commits and stick to it. For myself, I found this style convenient when I first indicate what I am doing. For example, add . After that, I indicate something on which I produce an action. For example, ui-bootstrap.js dependency . In most cases, such a record is more than enough. If there is still some explanatory inscription, then it is better to put it into a separate large entry, which we will talk about later. If the record is small, but very necessary, then you can add it directly to the commit. But it is better to think again whether this inscription is really necessary, or it will attract unnecessary attention.

It happens:
 dependency for managing ui-bootstrap.js components was added here on 18.06.2013 by olegafx

But better:
 add ui-bootstrap.js dependency

Big messages in commit

So what to do with big messages? Of course, write. For example, it may be important information with the message that your commit breaks the previous functionality, replacing it with a very cool and simple new one. This happens even in the largest projects, so it is very important to tell people how to make it work again.

The easiest thing to do is to add a blank line under the main commit message and start typing the information already there. By the way, here you can already write verbs in the past tense, if you really want. For example:

 replace twitter-bootstrap.css with pure.css Made UI much cleaner. BREAKING CHANGE. You need to use new class-names for grid-related elements.

We write a message with a small letter

It makes no sense to write the first word with a capital letter. With a little read much easier.

It happens:
 Add ui-bootstrap.js dependency ADD ui-bootstrap.js dependency

But better:
 add ui-bootstrap.js dependency

DO NOT use past tense

The simpler the better. The elapsed time makes it too difficult to read messages. Imagine that you are accessing Git: “Git, add,” “Git, delete,” etc.

It happens:
 added ui-bootstrap.js dependency

But better:
 add ui-bootstrap.js dependency

We remove extra punctuation marks

For example, why do you need a dot at the end of the message? So it is clear that it is finished. The same applies to the semicolon.

It happens:
 add ui-bootstrap.js dependency;

But better:
 add ui-bootstrap.js dependency

Russian language


There is nothing shameful about using the Russian language in commits. But this should be done only if you are 1000% sure that this code will be of interest only to Russian-speaking people. For example, you have a script for VK, which points to the map of all fans of Stas Mikhailov. Obviously, it will be of little interest to foreign citizens. And for the Russians, too, to be honest.

We brush commits before sending


All commits in the local repository can be called as you like. If it is easier for you to remember that “temp 1” is the first working version of some functionality, and “temp commit 2” is its corrected and refactored version, then please, no one will scold you. But. Huge BUT. Before sending, please bring your commits to the best view. For most cases, a great team will do:

 git rebase -i

With it you can arrange commits in the correct order, combine them, rename in accordance with all the rules of good form. Very powerful and useful command, but do not overdo it, but the code of the final version of some new functionality can be blocked by the code of the very first buggy version. Well, if you have already sent your code to a remote repository, then it is better not to use rebase, but it will only get worse.

Find your favorite style


I found one in the AngularJS project. They even have a separate document on commit commit. All the points about which I spoke above are in this document. And it is beautiful. Because I had to look for these moments from various sources, from my own experience, but here everything is already in one place and written in good simple language. A brief look at the main points.

Specify the type of commit

There are several predefined types:

These types can not always be easily distinguished when writing an application (for example, refactor and chore), so you can create your own.

Specify the scope

Immediately after the type of commit without any spaces, we indicate in brackets the area to which our commit applies. After that we write our standard commit.

For example, there may be a module scope:
 refactor(audio-controls) use common library for all controls

Or file scope:
 chore(Gruntfile.js) add watch task

What is it all for

As I said at the very beginning of the article, to save time and nerves! By simplifying the following operations:

Conclusion


I hope you are not bored. Please try to use a good naming style for commits in your projects. Other people will be very grateful to you for this.

That's all. If you have interesting examples of naming from your projects, I will be glad to see them in the comments. All errors in the text can be sent to private messages.

Enjoy your coding!

Source: https://habr.com/ru/post/183646/

More articles:


All Articles