Talk About Quality

Tom Harris

Code Review Comments

leave a comment »

In my previous post, Code Review Starter Kit, a reader pointed out that even some of the “minimum” items on my list — the ones that require written records — are more than what people may want to do. That is, if a method requires additional writing beyond the code, it’s too much.

Try Putting Code Review Results In the Code 

Code review output is sometimes called “issues”, or even “defects”, but I called them “comments”. Why?

It’s true that external tracking tools (issue trackers, spreadsheets etc.) are more powerful for recording and tracking code reviews. But what if you want to keep everything close to the code — a one-stop shop in your source control system?

Try this: have code reviewers put their short, concise issues and questions right in the code as comments, with the “//” or “/* … */” or other appropriate comment marker.

In a 1:1 or group meeting, the reviewer and author go over the comments. Any comments that the reviewer retracts or the author rejects are deleted. All the accepted comments remain in the code which is then checked in.

Now the code author can work through the code review comments one by one, removing them as s/he updates the code, or in some cases, updates the regular comments.

Give all the reviewers an IDE macro which marks their comments as “code review” with name- and time-stamp, and you’ve got almost painless tracking of code reviews.


Written by Tom Harris

September 14, 2006 at 10:56 am

Posted in Code Review

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s