Performing code reviews via internal forums

June 9, 2008

I am in the process of standing up an installation of Community Server (CS) Express at my day job. Despite all of the other things that come with an installation of CS, I am really just looking at it for the forum functionality. If I had my way, we’d be installing phpBB or vBulletin since they are single-purposed, free, no limitations in the free version, more polished/tighter UI and they don’t have all of the bloat of CS. However, we are a Microsoft shop and my installation of MediaWiki three years ago was pain enough to convince me to not try another WAMP/WIMP stack there. Not that it was difficult, but nobody wants to touch it with a ten-foot pole.

Regardless, despite my preference for the other forums, I don’t mind working with CS at all. The folks at Telligent have put a lot of effort into making Community Server a first-class, .Net-based, online community platform. The installation is really smooth, configuration is a breeze, it is very flexible and has a ton of features. In addition, I have worked with CS off and on since it used to be .Text and the original ASP.Net forums so I am fairly familiar with how it works.

Anyway, I want an internal forum at my day job to:

  • Help document and build up a knowledge base of all the little complexities/oddities/nuances/features required to support all of our applications. While we generally do a pretty good job at documentation, a fair amount gets lost in all of our enterprises content management options (Documentum, SharePoint, wiki, network file locations, emails, hallway conversations, etc.)
  • Help publicize some of our coding standards through public peer reviews. While we have an internal copy of Design Guidelines for Developing Class Libraries (aka Framework Design Guidelines) on our wiki that we customize per our needs, with the constant flux of developers, we still have a lot of crappy code being generated and put into production.

The first bullet is the typical reason for implementing an internal community or forum. But why would I want to conduct peer reviews via an online forum and not in a meeting or at least provide comments directly in source code?

  • Meetings are nice, but they are a PITA to schedule (room, resources, people, etc.) and don’t provide any value to the people who weren’t in attendance (sick, vacation, conflicts, future employees, etc.). In addition, it can provide a little bit of anonymity for the reviewee by just posting a method or class without revealing the source location or developer that wrote it. They would know who they are, but they don’t necessarily need everyone else to know.
  • As far as making the comments in code, I don’t feel that it provides a large enough audience (only the developer making the changes would ever see them). In addition, after all of the changes were made per the comments, you would (hopefully) be left with a clean method or class that doesn’t give any indication of the struggles it took to get there. Sure it is in the version control system, but who is ever really going to look in there to see the trials and tribulations that it took?

With a forum-based peer review you overcome the obstacles and limitations of meetings and comments in code.

  • The reviewer can conduct the code review on their own time.
  • The reviewee can digest they comments on their schedule (and they don’t have to frantically scribble notes in a meeting).
  • In addition, since it can often be hard to get multiple senior people in a room at the same time, the forum allows others to contribute when and where they see fit.
  • In addition, capturing the back and forth between the interested parties is very values.
  • Not too mention the benefit of referring new employees to the forum during their first couple of days to get a feel for how things are done in your shop.
  • Code changes made as part of a review can have a note on check-in referring back to the thread to help document how that particular piece of code got to where it is.
  • And we can’t forget about links. If your standards documentation is fairly granular, you can link to the specific standard that is in question.

In the thirteen years and five companies that I have developed for, I haven’t run across forums being used as a code review platform/tool, but I definitely want to give it a shot. We’ve all seen the "Why doesn’t this work?" or "How does my code look?" posts on various public forums but I hope to put something a little better in place internally. As Jeff Atwood says, "Code Reviews: Just Do It." If this doesn’t work out, I’ll have to check out Peer Reviews in Software: A Practical Guide. If you have any comments or suggestions based on experience, please let me know below.

Of course, in order to facilitate the process, I needed to make some minor changes to CS to support syntax highlighting. This post originally started out to document those tweaks but it got hi-jacked. Maybe on my next post!

Popularity: 11% [?]

Share This

Posted by Matt Smith | Filed Under General 

Comments

Got something to say?





MyHomePoint

Having trouble keeping track of everything going on at home? Is the refrigerator organizer not cutting it anymore? We feel the same way...
Check out MyHomePoint »

Latest Blog Posts

Close
E-mail It