Re: Formal code review specifications and reporting format

Hello Nuke

I'm of the personal opinion that the reason we have come this far without developing a really good standard for code review is that there is no such thing.

As Ferrency points out, there are many reasons that one could possibly want to do a code review. Finding one template that covers all of those would be very hard. For example, a code review done for the purpose of job performance review would probably not be very useful if you were looking for bugs. Likewise, I don't think I would want my performance review to be dependent on the number of bugs in my code. :) One solution might be to have an all-encompasing template to cover all bases. But, the problem with that is it would be so long and/or complicated that nobody would ever want to use it!

pdcawley also touches on an issue that was recently brought up by stephen in Failure To Refactor. That is that not all programmers are working at the same level. Without the same experiences, we don't look at code the same way.

I would suggest that a more fruitful endeavor might be to work on developing a standard template to be given to the reviewer that specifies what is to be reviewed, and how to review it.

Comment on Re: Formal code review specifications and reporting format

Replies are listed 'Best First'.
Re: Re: Formal code review specifications and reporting format by Nuke (Scribe) on May 16, 2002 at 20:24 UTC
Those are all good and very valid points. What I'm proposing here is that we create a generic template that could be used both as a checklist and a submission format when the review is complete. As I mentioned, the template would be a starting point, and could/should be modified as needed. Those who are new to code reviews would have a great checklist to get them started, and those who are experienced would have a common format to start with that could be modified to suit the code being reviewed. A common submission format would also allow the creation of parsing routines to do all manner of interesting things with the contents of the review. As long as folks understand that this is just a starting point, and they keep to the format of the review, I think we could end up with a very flexible and robust system for accomplishing this. I may disagree with you on what needs to be reviewed, but it's moot if we can both review code in whatever way we see fit. If we can get an agreement to this, perhaps we could move on to the next stage and talk about the implimentation of the above. (Do we create scripts to help us do this, or just a text template? Maybe a script that spits out a text template based on initial input from the reviewer? :) ) Nuke nuke@nuke3d.com www.nuke3d.com	[reply]

Replies are listed 'Best First'.

Re: Re: Formal code review specifications and reporting format
by Nuke (Scribe) on May 16, 2002 at 20:24 UTC

Those are all good and very valid points. What I'm proposing here is that we create a generic template that could be used both as a checklist and a submission format when the review is complete. As I mentioned, the template would be a starting point, and could/should be modified as needed. Those who are new to code reviews would have a great checklist to get them started, and those who are experienced would have a common format to start with that could be modified to suit the code being reviewed.

A common submission format would also allow the creation of parsing routines to do all manner of interesting things with the contents of the review.

As long as folks understand that this is just a starting point, and they keep to the format of the review, I think we could end up with a very flexible and robust system for accomplishing this. I may disagree with you on what needs to be reviewed, but it's moot if we can both review code in whatever way we see fit.

If we can get an agreement to this, perhaps we could move on to the next stage and talk about the implimentation of the above. (Do we create scripts to help us do this, or just a text template? Maybe a script that spits out a text template based on initial input from the reviewer? :) )

Nuke
nuke@nuke3d.com
www.nuke3d.com

[reply]