Improve Software Quality With Code Review in Two Simple Steps

Code reviews help spread knowledge, catch bugs in advance and reduce technical debt. Together with test-driven development or pair programming they can greatly increase code quality and maintainability. We are in no way sorry for implementing it in our R&D team, and we use it while developing Polarion.

So now that you are convinced that code review is what you must have, the question is: how to approach it? There are various tools for various version control systems, but you have Polarion and would like something integrated. Or you want to start quickly and maybe transition to something more robust later. In this article, I’ll show you how to do code review in just two simple steps based on our experiences.

In Step 1 we will present the task-centric code review process suitable for everyone. For cases where your code resides in Polarion’s default Subversion repository and you would like to have more fine-grained reviews, then there is the option of a commit-centric process extension described in Step 2. We do not offer a simple solution for per-commit code review (the way GitHub does it, for example), but there are plenty available out there.

 Step 1: Track tasks for review

OK, so you have decided that code review is what you need. What is absolutely necessary to define? Who is going to do the reviews and how will the reviews be tracked?

Reviewers are pretty straightforward, as a project role for that purpose is easy to configure in the project’s User Management administration, and it’s quite logical. For the review tracking we recommend configuring a special workflow status(e.g. “Awaiting Code Review”) with a relevant workflow action (e.g. “Send to Code Review”). The status should not be bypassable, and every implementation task must go through it. In our experience the best place for it is right before QA does the final test round/sign off on the implementation.

 Lastly we recommend to track who is doing the review in a custom field of type User enumeration (available since Polarion v. 2012 SR3):

To make it easier for code reviewers we created a special Wiki page named “Code Review” which lists items waiting for review and items being reviewed:

No need to go it alone

This seems like a good place to mention that we have rolled up our code review process into a free Polarion Extension. The wiki mark-up for the above page is packaged in the  code_review_wiki.txt file. All you need to do is copy the contents into a new wiki page, and do a minor tweak at the head of the file (described fully in the extension’s documentation).

How the process works

Let me give you a quick overview of how the process runs when we use it:

1. Developer commits work and marks the task available for review by changing its status.


2. Our pack of hungry reviewers sees the task on the top of the Code Review page and they compete for who puts him/herself first as a reviewer of the item.


3. When the item is reviewed, it is pushed to QA (if developer is lucky) or returned to developer (if developer’s luck runs out).

In accordance with Agile Manifesto we promote people over process and encourage reviewers to speak with the developer about any problems, rather than just changing the status of the task and writing comment. The latter is fine for the item’s history, but the person-to-person contact is really important.

To promote (friendly) competition there is also a Review Statistics section (it appears only if Wiki Scripting Tools are installed) at the bottom of the Code Review. For fun. Mostly. 🙂

Step 2: Track commits for review

If your code is in Polarion’s default Subversion repository, all those fancy code reviewing tools which are online and work with Git only are of no use to you. Yet you still want to be able to work on the revision level. Well, don’t despair, because we have something for you.

Just add new custom field which will hold the last reviewed revision and will be filled by the reviewer after the code review. That way everyone will know which revision was reviewed last.

OK, that sounds easy and nice, but how to prevent some revisions from slipping under the door – either not linked to any task or linked to some already-reviewed task? For that we offer small script (the Polarion Scripting extension is required) called CodeReviewChecker.groovy. After installation according to the Scripting extension, it can be scheduled in the global Administration / Scheduler to run regularly. You’ll find the XML to set up the job among the goodies in the documentation of the aforementioned Code Review extension.  Notification is sent when some revision is not linked at all or is linked to resolved item with last reviewed revision set to older revision:

Go forth and review!

We hope that you will find our little solution useful. It does not matter which way the code review is done (unless a certain way is mandated by regulatory bodies)… whether it is task-centric, commit-centric or per-commit review, or whether it is a custom solution, our little Polarion-integrated solution or a third-party tool. The only thing that matters is enabling developers and reviewers to concentrate on the code and improve it together.

---