Komit log: why is it really needed?

Published on August 14, 2008

Komit log: why is it really needed?

    Developers have long been accustomed to using version control systems. For some, this is a natural transition, someone initially 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 the commit - the code is fixed" stumbles upon the fact that the process of committing requires writing a log of the commit . The first solution is to leave the log empty or write something from:

    • "Fix bug";
    • "Committed everything that he did";
    • "Test commit";
    • “Corrected a typo”;
    • etc.


    Why is that bad?

    One answer to this question is that the commit log is documentation for the code and for the change. An ideal commit log should allow you to understand what happened in each revision without looking at the change itself (diff file) from the history of changes to a particular file. The commit log may contain additional meta-information: ticket number, name of the person who conducted the code-review, links to other commits, etc.

    Trying to satisfy the above requirements, the developer will often take the ticket title and write it in the commit log. However, most often the ticket is formulated in terms not of development, but of the original task, for example: "Indent 10 pixels between blocks A and B". Such a phrase as a commit log in a CSS file provides information about the change, but what information does it givereading such a log? After all, in fact, for example, a new CSS class was created with a name like this, some style was removed from another CSS class, etc. That is, the change itself is described in another language, not in the language of the project manager. It would be useful to have both representations of the commit, for example: Such a commit log has become much more informative, according to which the project manager can understand the meaning of the change (if he wants), and each developer understands the purpose of the change and exactly what changes occurred to the file in this revision. What is new in this commit log compared to the log: “committed CSS fix”? I think the main advantage is verbalization

    Сделать отступ 10 пикселей между блоками А и Б: был
    создан новый класс blockC, из класса blockA удалено
    padding-bottom: 0.5em, т.к. все paddingи перенесены в
    класс blockC.

    Тикет: #1734






    changes. And it’s not even for the reader of 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 new code on production servers. For these hours, the code cannot go through the natural stages: lay down for a “couple of days” so that the author can return to it with a “clear look”, the code review does not have time, other developers do not have time to get it from the repository, etc. While the bulk of the code is better studied and tested over time from one release to another. But very often we make mistakes simply because we lose sight of important details due to some other reasons: lack of experience, fatigue, frequent switching between tasks, etc.

    The programming process is non-verbal. It begins with a task set not in terms of a developer, but in terms of a customer. And often this formulation is somehow transformed in the mind of the developer into a concrete solution in terms of a programming language without fixing intermediate results on words. The code in the programming language does not contain the formulation of the problem in terms of the developer, it contains a solution that possibly solves the original problem, possibly introduces some errors (bugs).

    The code is written, and now the time has come to commit the change to the repository, which means writing a commit log! And this is the time to try to verbalize your change in natural language. If you restrict yourself to unsubscribing from the “fix bug” type or copy part of the phrase from the ticket, the verbalization process does not turn on, because we do not formulate anything. And let's try to formulate in good Russian what exactly we changed, why we changed, what consequences (possibly) it has for another code? In order to formulate exactly what exactly we have changed, you will need to look at the diff of the current change, which is wonderful, this captures the attention on each block of changes in an attempt to examine each line of code, to summarize the changes with a common idea, without missing important details.

    The process of formulating the commit log itself in a 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 change, i.e. Share your change with other developers. Probably, many noticed that sometimes it’s enough to go to another developer for help and talk about the problem so that a solution immediately appears in your head. It is the process of verbalization of our otherworldly, fantastic activities of programmers, which consists in translating the customer’s thoughts into phrases of the programming language, which makes it possible to understand the essence of the changes made and find a hidden error in the code. Therefore ... write good commit logs!