Log comet: why is it really needed?
Developers have long been accustomed to using version control systems. For some, this is a natural transition, someone first perceives the version control system as some additional complication of their work, but working on a project in a team is impossible without this tool.
Very often, the transition from thinking “I saved the file - the code is fixed” to thinking “I made a commit - the code is fixed” stumbles upon the fact that the commit process requires writing a log of the commit . The first solution is to leave the log empty or write something from:
Why is that bad?
')
One answer to this question is that the commit log is documentation for the code and the change. The ideal comit log should allow you to understand what happened in each revision, without looking at the change itself (diff file), in the change history of a specific file. The comit log may contain additional meta-information: the ticket number, the name of the person who conducted the code-review, links to other commits, etc.
Trying to meet the above requirements, the developer will often take the ticket header and enter it in the commit log. However, most often the ticket is formulated in terms of not the design, but the original problem, for example: “Indent 10 pixels between blocks A and B”. Such a phrase as a log of a comit in a CSS file reports information about the change, but what information does it give to the reader of such a log? After all, in fact, for example, a new CSS class was created with the name such and such, some style was deleted from another CSS class, etc. That is, the change itself is described in a different language, not in the language of the project manager. It would be useful to have both of them, such as:
Such a log commit has become much more informative, according to it the project manager can understand the meaning of the change (if he wants), and each developer understands the purpose of the change and what changes have occurred to the file in this revision.
What gives such a log comit new compared to the log: “committed CSS-fix”?
It seems to me that the main advantage is in verbalizing the change. And it is not even for reading this log once, but for the writer. The programming process today, especially in web development, is very fast. We do not write pseudo-code, rarely draw diagrams, often it may take several hours between setting a task and laying out a new code on a working server. During these hours, the code cannot go through the natural stages: lie down for a couple of days so that the author can return to it with an uncomplicated look, do not have time to go through the code review, other developers will not have time to get it from the repository, etc. While the bulk of the code turns out to be better studied and tested from one release to another. But very often we make mistakes simply due to the fact that we lose sight of important details due to some other reasons: lack of experience, fatigue, frequent switching between tasks, etc. How to ensure the quality of development in such conditions?
The programming process is non-verbal. It begins with a task, not in terms of a developer, but in terms of a customer. And often this formulation is somehow transformed in the developer’s mind into a specific solution in terms of a programming language without fixing on words intermediate results. The code in the programming language does not contain the statement of the problem in terms of the developer, it contains some solution that, possibly, solves the original problem, perhaps introduces some errors (bugs).
The code was written, and now it’s time to fix the change in the repository, which means to write the commit log! And this is the time to try to verbalize your change in natural language. If we confine ourselves to the reply of the “fix bug” type or copy a part of a phrase from a ticket, the verbalization process is not included, since we formulate nothing. And let's try to formulate in good Russian what exactly we changed, why we changed, what consequences does this have (possibly) for another code? In order to formulate exactly what we changed, you will need to look at the diff of the current change, which is great, it fixes attention on each block of changes in an attempt to examine each line of code, summarizing the changes with a general idea, without losing important details. This additional view on diff changes allows you to find simple technical errors, such as the lack of a docblock, and non-trivial ones — forgotten debugging statements, changes made temporarily during the programming process, “less” instead of “more”, etc.
The process of formulating the log of the committee itself in natural language allows us to find logical errors in the change, when we understand that our correction is incomplete, redundant, contradictory, does not solve the original problem, etc. Magic consists precisely in an attempt to formulate a story about a change, i.e. tell about your change to other developers. Probably, many people noticed that sometimes it is enough to come to another developer for help and tell about the problem so that a solution appears in my head. It is the process of verbalization of our otherworldly, fantastic activity of programmers, which consists in translating the thoughts of the customer into the phrases of a programming language, allows us to realize the essence of the changes made and to find the hidden error in the code. Therefore ... write good logs of komits!
Very often, the transition from thinking “I saved the file - the code is fixed” to thinking “I made a commit - the code is fixed” stumbles upon the fact that the commit process requires writing a log of the commit . The first solution is to leave the log empty or write something from:
- "Fix bug";
- “I committed all that I did”;
- "Test committee";
- "Corrected typo";
- etc.
Why is that bad?
')
One answer to this question is that the commit log is documentation for the code and the change. The ideal comit log should allow you to understand what happened in each revision, without looking at the change itself (diff file), in the change history of a specific file. The comit log may contain additional meta-information: the ticket number, the name of the person who conducted the code-review, links to other commits, etc.
Trying to meet the above requirements, the developer will often take the ticket header and enter it in the commit log. However, most often the ticket is formulated in terms of not the design, but the original problem, for example: “Indent 10 pixels between blocks A and B”. Such a phrase as a log of a comit in a CSS file reports information about the change, but what information does it give to the reader of such a log? After all, in fact, for example, a new CSS class was created with the name such and such, some style was deleted from another CSS class, etc. That is, the change itself is described in a different language, not in the language of the project manager. It would be useful to have both of them, such as:
10 :
blockC, blockA
padding-bottom: 0.5em, .. padding
blockC.
: #1734
Such a log commit has become much more informative, according to it the project manager can understand the meaning of the change (if he wants), and each developer understands the purpose of the change and what changes have occurred to the file in this revision.
What gives such a log comit new compared to the log: “committed CSS-fix”?
It seems to me that the main advantage is in verbalizing the change. And it is not even for reading this log once, but for the writer. The programming process today, especially in web development, is very fast. We do not write pseudo-code, rarely draw diagrams, often it may take several hours between setting a task and laying out a new code on a working server. During these hours, the code cannot go through the natural stages: lie down for a couple of days so that the author can return to it with an uncomplicated look, do not have time to go through the code review, other developers will not have time to get it from the repository, etc. While the bulk of the code turns out to be better studied and tested from one release to another. But very often we make mistakes simply due to the fact that we lose sight of important details due to some other reasons: lack of experience, fatigue, frequent switching between tasks, etc. How to ensure the quality of development in such conditions?
The programming process is non-verbal. It begins with a task, not in terms of a developer, but in terms of a customer. And often this formulation is somehow transformed in the developer’s mind into a specific solution in terms of a programming language without fixing on words intermediate results. The code in the programming language does not contain the statement of the problem in terms of the developer, it contains some solution that, possibly, solves the original problem, perhaps introduces some errors (bugs).
The code was written, and now it’s time to fix the change in the repository, which means to write the commit log! And this is the time to try to verbalize your change in natural language. If we confine ourselves to the reply of the “fix bug” type or copy a part of a phrase from a ticket, the verbalization process is not included, since we formulate nothing. And let's try to formulate in good Russian what exactly we changed, why we changed, what consequences does this have (possibly) for another code? In order to formulate exactly what we changed, you will need to look at the diff of the current change, which is great, it fixes attention on each block of changes in an attempt to examine each line of code, summarizing the changes with a general idea, without losing important details. This additional view on diff changes allows you to find simple technical errors, such as the lack of a docblock, and non-trivial ones — forgotten debugging statements, changes made temporarily during the programming process, “less” instead of “more”, etc.
The process of formulating the log of the committee itself in natural language allows us to find logical errors in the change, when we understand that our correction is incomplete, redundant, contradictory, does not solve the original problem, etc. Magic consists precisely in an attempt to formulate a story about a change, i.e. tell about your change to other developers. Probably, many people noticed that sometimes it is enough to come to another developer for help and tell about the problem so that a solution appears in my head. It is the process of verbalization of our otherworldly, fantastic activity of programmers, which consists in translating the thoughts of the customer into the phrases of a programming language, allows us to realize the essence of the changes made and to find the hidden error in the code. Therefore ... write good logs of komits!
Source: https://habr.com/ru/post/36973/
All Articles