About code review

A cost-effective way to improve several aspects of code quality is pass the source code through a process of peer review by one or more colleagues. Of course this is possible only if the programming team is composed by several programmers.

Here is a simple and effective code review process.

A programmer (“writer”) writes a new module or edits and existing one by himself.

When he believes the change is good enough, he releases the change in a shared repository in a state of “not reviewed” and asks another programmer (“reviewer”) to review it. Such reviewer should be not less expert than the writer with the technologies involved.

The reviewer reads carefully the new new module or the changelog of the applied changes. Every time he finds some unclear or dubious or blatantly wrong line, he writes in a separate document his objections, possibly with a proposal for a better replacement. Notice that the critiques may regard not only the correctness, but also  the style, like a missing or misleading comment, a missing or misleading indentation, an unclear naming of an identifier.

The critique document is passed (via e-mail or another volatile support) to the writer. The writer examines every critique and may reject it, or adopt it applying appropriate changes to the code. Therefore he releases a new code revision, accompanied by the a document in which he lists which critiques have been adopted and explains why the others have been rejected. Then those documents are passed to the same reviewer.

The reviewer repeats the review process on the new revision, and the cycle is repeated, until there is no more critique left, or there are controversies left. If there are remaining controversies, they are passed to a third person, that is possibly more expert or more accountable (or both) than the writer and reviewer (“judge”), and his decision will be the final one. Typically such judge is the project manager.

The programmer must apply the changes suggested by the judge, and the reviewer should review also such changes, to detect overlooks or misunderstandings.

When there is no more remaining critique, the state of the last revision passes to “reviewed”.