03 May 2009

Not Enough Code Review Secrets

I just finished reading Smart Bear Software's book "The Best Kept Secrets of Peer Code Review." It's available for free (including shipping) from their website. (I have no affiliation with Smart Bear, but my company has a site license for Code Collaborator.)

The book does a good job of covering different aspects of covering the why and how of software code review, although it's tarnished by the occasional statement biased in favour of a code review tool like Smart Bear's Code Collaborator (as opposed to email or over-the-shoulder reviews).


The Essays

The first several essays (The Case for Peer Review, Resistance to Code Review) aren't very useful unless you're still convincing your co-workers of the benefits of peer review. If everyone's on board, then there are a few essays (Social Effects of Code Review, Questions for a Review Process) for team leads on how to prevent code reviews from being perceived as personal attacks on coding ability or the importance of separating code reviews from employee reviews.

If you're interested in the science of reviews, then there are several essays (Brand New Information, Code Review at Cisco Systems) that go into what works, doesn't work, and how well it works. Other essays (Measurement & Improvement) talk about metrics and how you can gauge the effectiveness of your team's review process (along with how Code Collaborator can help provide these metrics).

For those of us who are only concerned with doing the reviews, the most useful essay is not so much about code review as it is about software process in general. The SEI Perspective discusses the Software Engineering Institute's Personal Software Process and Team Software Process. Both processes are geared toward making developers more effective at their job -- as individuals and as a team, respectively. The process includes making a personal review checklist and tracking what defects you commonly introduce so you can eliminate them and bug estimation techniques.

Overall

In the end, there's not much for anyone who is solely interested in improving their code reviews. If you're not interested in the science of code reviews, then this book may be a bore. On the other hand, if you're interested in the motivation behind code reviews, or want to look at some numbers from review studies or from your own code reviews, or you don't get why code reviews are useful, then this book has what you're looking for.


Reader's Thoughts

In general, I liked the book. I found the science behind code review interesting and I liked seeing the results of case studies. I was disappointed (but not totally surprised) at the lack of magic advice to make your reviews more effective. The essays were written in an engaging tone without sounding like a textbook. You can get the book for free and at 160 pages, it makes for decent light reading. It's a small form factor (the size of a DVD case), so it's convenient to read on the bus.


Code Collaborator

In addition, some thoughts on Code Collaborator: It's a well-designed tool. The integration with Perforce is simple (it's a command-line client that uses Perforce's Custom Tools), but effective (creating a review or adding to an existing review are all you need).

The code reviews are accessed through a web interface. You have a dashboard showing your reviews. You can look at files for each review, diff them through the web interface or download them and diff them with a local viewer (handled with the local client so there's no hassle). However, I haven't used it extensively because my team prefers over-the-shoulder reviews. Nothing in "Best Kept Secrets" convinced me that a tool is necessary. (Having metrics would be a nice bonus, but not necessary.)

Have a link to a blog post or article that does a good job describing how to improve your code reviews? Respond in the comments!

2 comments:

Jason Cohen said...

Thanks for the review David!

You're right that half the book is geared towards encouraging people to do code reviews at all. You're also right that there's an occasional mention of the tool, but always with a "fair warning" that we sell a tool.

That is, of course the reason we're giving a book away for free is to promote Smart Bear and Code Collaborator, so perhaps you can excuse a handful of plugs. :-)

In fact, your point at the end -- that the book didn't specifically convince you that a tool is necessary -- is perhaps proof that we weren't unreasonably heavy-handed in promoting our business.

You're also right that there's not a magic bullet for better code reviews, although you're right that perhaps we could have done more in making suggestions.

To that end, on our website (http://smartbear.com) you'll find a collection of blog posts and articles around the Internet (that we DIDN'T write!) that present clear ideas for better reviews.

In any case this was a terrific review, thanks!

Unknown said...

Just FYI, our lighter weight product, Code Reviewer, is available at a special price this week: $5 for 5 licenses (July 13-17, 2009 only). More details here: http://smartbear.com/code-review-5-for-5.php