Code Review Comments

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.