This article is reproduced in: Ape 2048 Website ➤ https://www.mk2048.com/blog/blog.php?id=ijhckcik2j
A total of 1926 words, reading takes four minutes. All engineers know that the code is written once and modified many times, and then read more, code readability of the importance of self-evident, but there is also a very important record will read many times in the evolution of the project that is submitted Git log, log which submitted the largest amount of information should be the commit message, this article was inspired by Linux author Linus Torvalds to commit mesage on GitHub Tucao .
Git Log pain
In "The Art of Readable Code" this classic book, there is a vivid metaphor, measure the readability of the code is the number of times per minute WTF when reading the code, while reading Git commit history when I do not know how much you have second burst foul language? Do not believe? You open the company's fastest evolution project execution git log, too little information is misleading and even commit messagevery common, such as:
fix => 这到底是 fix 什么？为什么 fix？怎么 fix 的？
update => 更新了什么？是为了解决什么问题？
test => 这个最让人崩溃，难道是为了测试？至于为了测试而去提交一次代码么？Perhaps, you are in such a commit message also contribute to a force it.
Address the issue
Let's Git commit log down to look at the typical back-end log, which is as below access log:
remote_addr=[127.0.0.1] http_x_forward=[-] time=[19/Apr/2017:07:28:13 +0800] request=[GET /admin/edu/exam_scores/index/225 HTTP/1.1] status=[200] byte=[15745] elapsed=[0.309] refer=[http://stu.youcaiedu.com/admin/edu/contests] body=[-] ua=[Mozilla/5.0 （Macintosh; Intel Mac OS X 10_12_4） AppleWebKit/537.36 （KHTML, like Gecko） Chrome/57.0.2987.133 Safari/537.36] cookie=[JSESSIONID=aaaXlJyT6Ju-K-FbLuWPv; pgv_pvi=7986424832; pgv_si=s905561088; easycms=a16pbumhusksq3vpcogcv2n715; toolbarDisplay=hide; _ga=GA1.2.1604145244.1486802034] gzip=[7.71]Good access logcontains what elements of it?
- Time requested by the user (Time);
- Address (request) a user request comes from (REFER);
- Users Source (remote_addr);
- The server response (status, byte, elapsed);
- ...
Knowledge memories at school, how to accurately describe the incident? Yes, that's 5W1Hthe law, specifically, that is, who (who) at what time (when), what place (where) because of what (why) and do what (what), he is how to do (how), access logis typical event log, the access logrecords can reference 5W1Hmethods to record, then you look at, it also will not miss the details.
Back to the topic, is not the essence of the event log on Log Git it? The line must be out of the question, raised demand for the product, the engineers do their own remodeling or technical improvements will lead to its change. If there is no detailed record of the details of each change, the code Review of how people know what you do? After the on-line experience problems how to trace? The couple took over the code how to understand?
Solve the problem
Because of the special nature of Git, Git kernel has been able to 5W1Hinside who, when a commit meta-information recorded, and where R & D activities obviously do not need to record, engineers really need to focus on is what, why, how, these three It is an important carrier of information commit message. I believe reading this, you already know what I want to say.
The following can help you write proposes a high practices readable commit message, this method is not original, the earliest practitioners from this article . In simple terms this submission is to record the what, why, how in the commit message, then how to integrate this idea into your development workflow inside it? Refer to the following steps is completed:
1. Set .gitmessage template
It is built to support Git, you can commit message each commit setting a template, each time submitted, could make you follow this pattern of thinking to write commit message, such as the following is my template stored in ~/.gitmessage:
What: 简短的描述干了什么
Why:
* 我为什么要这么做？
How:
* 我是怎么做的？这么做会有什么副作用？2. Let template into force
Git global configuration ~/.gitconfigadd the following configuration:
[commit]
template = ~/.gitmessage3. Embrace new template
Once you've configured the template, you have to give up directly specify when submitting commit messagethe practices that this manner of the following:
git commit -m "<commit message here>"Because this submission is not pop template allows you to fill and submit the order you should read:
git commitSpecific operation is shown below in FIG action:
As Amir Khan gave his daughter to do when wrestling tactics guide had to say: take a fifth of difficult, but not impossible. Habits are not easily fixed, but it is feasible, if you realize this, from the habit is very near.
4. students to use Vim
In order to better commit message reader experience, you may need to consider commit messagethe contents inside the wrap, let content control in width easily can see, the students can use Vim in your ~/.vimrcadd the following configuration inside:
autocmd Filetype gitcommit setlocal spell textwidth=805. The most important thing is the content
Write readable high commit messageneed you to do a serious in-depth reflection on the changes each commit seriously to answer a few questions mentioned above:
- What: a brief description of the changes
- Why: Why am? Is to explain the necessity of the changes, may be linked sources of demand, the task card, or other relevant information;
- How: change has been made? It should be noted that the use of any method (such as data structures, algorithms) to solve the problem of which;
In addition, there is a very important point is that this revision what side effects may have, because the project is to continue to do trade-offs, this revision is what is left after the pit? What needs work? They can be recorded commit messagein.
In essence, the form of the frame just above your thinking and recorded content, what really matters is that you have to think carefully about several issues, because to a certain extent, commit messageis a document, a living document, which records all changes warehouse .
to sum up
How to make your code can be traced essential quality is excellent engineer, I believe reading this, you write about how high readable commit messagereason, the benefits, the method has a clear understanding of the paper come Zhongjue, know this practice is essential, then you need to put this method to the actual work, believe me, then you will begin to appreciate colleagues find you, to follow you.
One More Thing
The author Wang Shijun, commercial reprint please contact the author authorized, non-commercial reprint please indicate the source. If you think this article helpful to you, please praise! If you have any questions about the contents of the text, please leave a message discussion. I would like to know what to write next? Welcome to subscribe to my nuggets column or know almost Column : "front-end Week: Let your pace to keep up with the times in the front field."