Review code in the comments
Review of the code is useful and can be done in different ways: by patch by mail, sitting side by side or using specialized tools / plugins. Each method has its pros and cons, but we offer another one that allows us to use what we already have.
The method will be of interest to a small team using a distributed version control system (git, mercurial, bazaar) with an embedded methodology for developing features / tasks / bugs in branches (for example, gitflow). Code editors in the team support parsing comments for certain keywords (for example, TODO). A full-featured specialized tools for reviewing the code can not be implemented, because they are paid and do not have a line in the budget; either free, but not easy to install, or have questionable usability; or in a particular case they may be a sparrow king-cannon.
The general idea - features (bugs, tasks) are developed in separate branches, a la gitflow, and then published on a server - you can even central. The reviewer writes comments in the style of TODO, but with a special tag, for example “REV”:
')
Any modern IDE can extract and filter a TODO. This is exactly what Eclipse and Netbeans can do, and JetBrains and other paid editors simply have to do it. As a result, you can change the comments in the branch, until everything becomes clear and they do not end. At the end of the process, when the code becomes better, the branch can be safely compressed (squash) and merged into the main one (develop). All comments at the end are erased and should not get into the code, which can be hugged.
We emphasize that this method is not offered as one and the most correct, but is one of the options in certain conditions. If you know or have already used something similar, but have not formalized, describe it boldly, and improvements to the method are also welcome. Even if this method does not suit you, then perhaps it will push you to some other ideas.
Preconditions
The method will be of interest to a small team using a distributed version control system (git, mercurial, bazaar) with an embedded methodology for developing features / tasks / bugs in branches (for example, gitflow). Code editors in the team support parsing comments for certain keywords (for example, TODO). A full-featured specialized tools for reviewing the code can not be implemented, because they are paid and do not have a line in the budget; either free, but not easy to install, or have questionable usability; or in a particular case they may be a sparrow king-cannon.
Process
The general idea - features (bugs, tasks) are developed in separate branches, a la gitflow, and then published on a server - you can even central. The reviewer writes comments in the style of TODO, but with a special tag, for example “REV”:
')
$ourcoolcode = 123; // REV ? echo $ourcoolcode; Comment syntax
Comments can be either single-line or multi-line, depending on the specific language.
/** * $TAG $status $title * $commentor1 $comments * $commentorN $comments */ - $ TAG - unique to the project code, not TODO, not XXX, etc, but, for example, REV. Must not exist in comments in the current project code.
- $ status is an optional parameter that can indicate the status: “+” - the question is closed or the problem is resolved; “!” - we have a problem, and the number of characters may indicate the severity of the problem.
- $ title - the title of the issue / problem.
- $ commentor1 / $ commentorN - (optional) a certain designation of the authors of comments, in order to distinguish some comments from others.
- $ comments - either comments of the author of the question / problem, when the title does not fit everything, or comments of the person who answers.
Comments can be either single-line or multi-line, depending on the specific language.
Any modern IDE can extract and filter a TODO. This is exactly what Eclipse and Netbeans can do, and JetBrains and other paid editors simply have to do it. As a result, you can change the comments in the branch, until everything becomes clear and they do not end. At the end of the process, when the code becomes better, the branch can be safely compressed (squash) and merged into the main one (develop). All comments at the end are erased and should not get into the code, which can be hugged.Abstract example in vacuum
Advantages and disadvantages
Advantages of the method:
- minimal implementation cost - absolutely native tools are used - editor with standard settings / plug-ins and version control system;
- issues and defects are immediately visible in the editor;
- works on a plane (: also like git and other dvcs);
- when working with the code, we can open the comparison mode, see what is changed and write special comments here
And of course the disadvantages (with variants of workarounds):
- knee pads and the fact that we now set up not some tool, but our editors and put hooks in repositories, though: hooks can be written once and put on a githab; setting the tools also describe once and put on the gitkhab wiki with pictures;
- it is necessary to maintain a certain discipline and abide by conventions that simply force up in ordinary tools, although everything can be completely organized with the help of hooks: can comments remain? do not allow commits to develop / master with them; can a commit log get clogged with “left” commits? compress them and inject them into the main branches;
- syntax and problem of long comments or discussions;
- preservation of history: as an option, in the final commit, the body should be done and painted on what they discussed and what they came to.
Conclusion
We emphasize that this method is not offered as one and the most correct, but is one of the options in certain conditions. If you know or have already used something similar, but have not formalized, describe it boldly, and improvements to the method are also welcome. Even if this method does not suit you, then perhaps it will push you to some other ideas.
Source: https://habr.com/ru/post/153867/
All Articles