October 14, 2012 at 17:51Review code in comments
Code review is useful and it can be done in different ways: by mail patches, sitting next to face to face 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 implemented methodology for developing features / tasks / bugs in branches (for example, gitflow). Code editors in the team support parsing comments for specific keywords (for example, TODO). A fully functional specialized tools for reviewing the code can not be implemented, as they are paid and do not have a line in the budget; Either free, but not easy to install or have dubious usability or in a particular case, they may be the sparrow king-cannon.
The general idea is that features (bugs, tasks) are developed in separate branches, a la gitflow, and then published on a certain server - you can even central one. The reviewer writes comments in the TODO style, but with a special tag, for example “REV”:
Any modern IDE can extract and filter TODO. Eclipse and Netbeans can do this, and JetBrains and other paid editors are simply obliged to do this. As a result, you can change the comments in the thread until everything becomes clear and they end. At the end of the process, when the code gets better, the branch can be safely compressed (squash) and merged (merge) into the main one (develop). All comments at the end are erased and should not fall into the code, which can be hooked with hooks.
We emphasize that this method is not proposed as a single and most correct one, but is one of the options under certain conditions. If you know or have already used something similar, but have not formalized, then feel free to describe it, method improvements are also welcome. Even if this method does not suit you, then perhaps it will prompt 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 implemented methodology for developing features / tasks / bugs in branches (for example, gitflow). Code editors in the team support parsing comments for specific keywords (for example, TODO). A fully functional specialized tools for reviewing the code can not be implemented, as they are paid and do not have a line in the budget; Either free, but not easy to install or have dubious usability or in a particular case, they may be the sparrow king-cannon.
Process
The general idea is that features (bugs, tasks) are developed in separate branches, a la gitflow, and then published on a certain server - you can even central one. The reviewer writes comments in the TODO style, 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. Should not exist in comments in the current project code.
- $ status - an optional parameter that can indicate status: “+” - the question is closed or the problem is resolved; “!” - we have a problem, and the number of characters can indicate the severity of the problem.
- $ title - the title of the question / problem.
- $ commentor1 / $ commentorN - (optional) some designation of commentators to distinguish some comments from others.
- $ comments - either the comments of the author of the question / problem, when everything does not fit in the title, or the comments of the one who answers.
Comments can be either single-line or multi-line, depending on the specific language.
Any modern IDE can extract and filter TODO. Eclipse and Netbeans can do this, and JetBrains and other paid editors are simply obliged to do this. As a result, you can change the comments in the thread until everything becomes clear and they end. At the end of the process, when the code gets better, the branch can be safely compressed (squash) and merged (merge) into the main one (develop). All comments at the end are erased and should not fall into the code, which can be hooked with hooks.Abstract example in a vacuum
Pros and cons
Advantages of the method:
- minimum implementation cost - absolutely native tools are used - an editor with standard settings / plugins and a version control system;
- questions and defects are immediately visible in the editor;
- works on an airplane (: like git and other dvcs);
- when working with code, we can open the comparison mode, see what is changed and write special comments here
And of course the disadvantages (with workarounds):
- kneeling and the fact that now we are setting up not a certain tool, but our editors and putting hooks in repositories, though: hooks can be written once and put on a github; also describe the tuning of the tools once and put the wiki with pictures on the github;
- you need to maintain some discipline and abide by conventions, which are simply forced in ordinary instruments, although absolutely everything can be organized with the help of hooks: can comments remain? do not allow commits with them in develop / master; can the commit log get clogged with “left” commits? compress them and pour already full ones into the main branches;
- syntax and problem of long comments or discussions;
- preservation of history: as an option, in the final commit, do a little more body and paint what was discussed and what it came to.
Conclusion
We emphasize that this method is not proposed as a single and most correct one, but is one of the options under certain conditions. If you know or have already used something similar, but have not formalized, then feel free to describe it, method improvements are also welcome. Even if this method does not suit you, then perhaps it will prompt you to some other ideas.