Code Reviews – How to Organize Code Review Process

code-reviews

I'm looking for a light-weight code review process. A couple of requirements, the reviewer must be able to do the review alone at the time of his/her choosing (not tied to check-ins), the reviewer must be able to easily find the target code, the review has to leave some document showing what was reviewed. I know there are tools available for code review but I work in a very ridig environment and introducing new tools is not an option.

One idea I've been thinking about is to create a new Visual Studio Task List token called REVIEW, and use it to mark the code that needs reviewing.

Something like,

// REVIEW doe_john: New method, not sure about the exception.

Then we would add a Review workitem in TFS (we're using the CMM template).

Another possibility, which I would actually prefer, would be to have developers create a TFS Review workitem and add links to code to it, but I don't know if this is possible. Obviously you can add a link to a file, but I'd like to have a link to a particular method.

PS. Posted originally to StackOverflow.

Best Answer

We used to do manual code reviews (i.e. no special tools) and this was the best method we found. Our development department doesn't have team foundation server, so I can't comment on that.

  1. All work is tied to a bug or an agile story that has a unique ID. When the work is checked in (or shelved, which is submission without actual check in), the description will always have this identifier.
  2. In a stand-up or over e-mail the reviewer would be notified that bug ### or story ### is ready for review.
  3. They do source control diff between new versions of the files and previous versions and copy/paste the output of diff into a word document. We have a code review word document template which is preset to use have 2 levels of headings: level 1-module, level 2-file name. It also defines formatting style for actual code (8pt Consolas). This step obviously was the biggest pain, but with Word template and Ctrl-A, Ctrl-C, Ctrl-V sequence, it's not that many clicks.
  4. Now that the document is in word, the reviewer can highlight the code in question and add comments using Word's review system.
  5. All documents are stored in a document repository and labeled with corresponding bug or story number.
  6. Once the document is done, the link to the repository is shared with original developer. Then we'd either have a code review meeting if changes were significant enough and need discussion, or just leave it up to original developer to go through comments on his own time.

After trying numerous manual methods, this was the one we found to have the least amount of overhead while allowing us to actually review every change.

However, our engineering team just rolled out Review Board and although I haven't used it that much yet, so far I'm loving what I have seen. It has all the flexibility of our word docs, but no more copy/pasting and manually fixing formatting. As an added bonus it keeps a permanent archive of all comments so you can go back years in time if you ever need to. Also it allows you do diffs of diffs, which is great when you want to do a review of a code review. This part we found to be very difficult with manual procedures because you can't see what was changed in response to first code review, instead you end up redoing the entire thing.

Although you did say you don't want to use tools, I'd strongly urge you to consider Review Board. It is open source and completely free. So you can roll it out for yourself and the 5 people you maybe working with. The rest of your company doesn't have to use this tool if they don't want to. And you don't need to worry about getting any purchase approvals.

== Update to comments from question: ==

On my team, we have people in NY, CT, TX, Poland and India. What makes things even more interesting is that extremely high percentage of the team doesn't know the product or technology all that well, so very few of us do most of the review. So yeah, senior devs are definitely busy. In the process I outlined, primary reviewer would do initial walk through the code independently on his own schedule. But afterwards we schedule a meeting and primary reviewer walks the coder through his comments. The meeting can have other reviewers, but they are considered secondary and are not obligated (but not discouraged from) to review every file or make comments.

I agree with others comments that having the final meeting in real-time, even if you have to use web conferencing is much better for knowledge transfer and for helping your new guys understand the code so that they'll start producing things that make your senior devs even busier. But again, that depends on the volume and type of comments, sometimes (very infrequently) comments are so minor that the meeting is skipped.

I can also relate to you when you say it's hard to roll out new tools. I work for a very large corporation and typically there's so many people involved that even outside of the fact that no purchases are ever approved, there are so many interests/agendas that nothing is ever agreed on. What's nice about Review Board is that you can skip all that and just start using with your small team and if you have to (if it really comes to that), you can host the web services on your own dev machine.

Related Topic