Making code reviews easier with Review Board [LWN.net]

By Jake Edge
January 16, 2008

Reviewing code is a thankless, but very important, task for any software project. For free software projects, the "many eyes make all bugs shallow" aphorism only works if the eyes actually focus on the code in question. Review Board is a web-based application that helps reviewers examine the code, while making it easier for a developer to track those reviews.

Borne out of frustration with the process of code reviews at VMware, Review Board has made a great deal of progress since being released last May. The idea behind it is to centralize all of the pieces that need to come together for a review: code diffs, screenshots of UI functionality, comments by other developers, etc. On many projects, reviews are handled by email, but that can be difficult to use; various pieces of the puzzle are spread around in multiple messages and locations.

Often a reviewer needs to see more context than a simple email diff provides or wants to comment on a related section of code that is not contained in the diff; each requires a reviewer to do more work. In a complicated set of changes, ensuring that the developer and any other reviewers can follow what code the comments pertain to can also be difficult. It is these kinds of problems that Review Board is meant to solve.

Review Board presents a side-by-side diff view, shown at right, with lots of extras, many of which will be familiar to users of other graphical diff tools. Changed lines are highlighted in different colors based on whether they are additions, deletions, or changes. Changes on a particular line are highlighted in a slightly darker color so that they can be distinguished more easily as well. The numbered tabs along the left edge provide a link to a reviewer's comments about that section of the code. This is where Review Board shows that it is much more than just a diff viewer.

Using AJAX techniques, Review Board allows a reviewer to interact very naturally with the code. They can highlight a certain section, which will pop up a text widget that records comments associated with that section of code. When other reviewers or the developer read those comments, the code snippet is included, with a link back to the code in the diff view. Each of these comments can then be commented upon which allows for a conversation about the code to develop.

It is not just code that can be annotated; screenshots of application functionality or bugs can be attached to reviews, as well. Sections of the screenshot can be highlighted and commented upon, as shown at left. This feature is an excellent example of where a web-based tool can shine; doing the same task in text-based email would be painful. Not all projects need it, but those that do will find it quite useful as anyone who has spent time trying to describe a UI problem in email will attest.

Inter-diffs is another useful feature that Review Board provides. Often in the code review process, several revisions of the original patch are made. It can be tedious to wade through a large diff, most of which has been uncontroversial (or resolved earlier) to get to the changes in the area of interest. Review Board has the ability to see changes between any two revisions of the patch, which should reduce much of the hassle.

Another thing that Review Board does is to assist in managing code reviews. When a developer posts something for review, various reviewers can be notified via email. Review Board keeps track of that information, presenting users with a "dashboard" view of their pending reviews, both those they submitted and those that others have asked them to do. This high-level overview is the first screen the user sees when they log on to the system, shown at right. This makes keeping track of work that needs to be done – or who to prod to get a review moving again – much easier.

Currently, Review Board best supports the Subversion and Perforce version control systems (VCS), but support for others, including distributed VCS Mercurial and git, are being actively developed and are usable in their current states. Released under an MIT license, Review Board is written in Python, using the Django web framework. Development is hosted at Google Code; the developers, unsurprisingly, uses the software for internal code reviews.

Other systems to assist in the code review process do exist. Codestriker is a Perl based web application that has similar aspirations to Review Board. Also of interest is Python founder Guido van Rossum's first project at Google: a code review system he calls "Mondrian". It is closely tied to Google proprietary code, though, so it seems unlikely to be released as free software – though it might make an appearance as a tool for Google Code projects to use.

Code reviews are very powerful, but generally painful to perform; any tool that claims that "Code reviews are fun again! ...almost.", as Review Board does, will be welcomed by many. It will be interesting to see whether a code review tracker becomes a standard part of newer free software projects. Over the last few years, we have seen the rise of distributed VCS, bug trackers, and wikis to assist in distributed development. Will Review Board – or something like it – be the next tool to be added?

(Log in to post comments)

Review pointer

Posted Jan 22, 2008 23:10 UTC (Tue) by Max.Hyre (subscriber, #1054) [Link]

Any suggestions on how to best go about code reviews when you have the luxury of everyone being in the same physical place?

Make sure everyone has already reviewed the code before the meeting. People should show up with their lists of comments, ready to start talking.

The alternative (everyone is reading the code for the first time) leaves people

distracted from understanding one section of code by someone starting to discuss another,
thinking a section is OK because it's been discussed by others,
and, probably worst,
unwilling to hold things up because they want to look more deeply into something that the rest are already finished with. It takes guts to say ``Wait a minute...'' when everyone else is ready to go on to the next page.

Such ``show and go'' reviews are much better than nothing, but it's a vast improvement if each reviewer has gone over the code before the get-together.

Making code reviews easier with Review Board

Posted Jan 24, 2008 9:16 UTC (Thu) by renox (subscriber, #23785) [Link]

[[ Any suggestions on how to best go about code reviews when you have the luxury of everyone
being in the same physical place? ]]

Having done some group review of code or specification, I think that there are two important
points:
- break the document to review into manageable thunk (otherwise the end is rushed)
- have someone in charge to ensure that one particular point doesn't take 90% of the time.
If one point takes too long, it should be put aside with someone in charge to ensure that it
is resolved (a dedicated meeting can be done).

The tools need to work together, too

Posted Jan 24, 2008 16:02 UTC (Thu) by jpetso (guest, #36230) [Link]

Review Board certainly seems to be a nice addition to an open source 
project's arsenal of quality assurance and coordination tools, but it's 
also yet one more tool that is to be separately updated, monitored for 
security announcements and likely adapted to the existing looks and 
infrastructure of the project's web presence.

Trac (for specific version control systems only) or [Bugzilla + repository 
viewer], Mediawiki, Mailman, Planet and/or self-hosted blog site, forums, 
perhaps an applications/plugins directory, and of course the actual main 
site... that's a lot different software to maintain, each of them coming 
with their own bugs and personality, and with different release cycles 
too.

Personally, I think the future lies in consolidation of those different 
features into one CMS that can handle all (or most) of those, and is still 
adaptable to a project's special needs. There might not yet be a solution 
that is as comprehensive as to cover them as good as the combination of 
the above, but I believe that stuff is in the works and will enable better 
integration and less maintenance effort in the long run. E.g. Drupal 
provides many of the mentioned features as plugins, and it will not be 
long until it reaches the power of Trac while still keeping its 
capabilities as a generic CMS.

"Specialized" applications like Review Board are definitely a nice push 
for the open source world to expand their mindset and get usable tools up 
and running quickly, but it would be interesting to also see articles on 
applications that grow their feature set more slowly but with higher 
integration. Imho, that area of software has an undeserved hard time with 
media as it's neither new nor explicitely specialized, while its potential 
as a useful integrated solution is higher in principle.