Hi all
I have never even thought about this, but some people seem to be documenting the code reviews, by documenting I mean keeping a log of what the problems were, which files to change, etc. Personally I think is a not a great idea because it makes it way less dynamic and I would be afraid it could be used improperly, what are the views out there?
Of course not.
Unless you want to learn from it (and enable others to learn).
I vote no. Mainly because it provides no benefit, except to the finger pointers.
Yes you should, and you should also document code review expectations and approach. It doesn't have to be a lot of documentation, but having at least some will help you later on.
I think it depends on the review.
If you're doing a 'formal' review, and you're reviewing many files (or many lines of code), then I'd say it is necessary, as you would surely forget some points that are mentioned in the review.
If you're reviewing a small, simple piece of code, then there's nothing wrong with jolting a few remarks on a piece of paper, or just mentiong that one remark to the reviewee.
Leaving things unlisted is okay if the attendees generally trust the agreed changes to be made, and tend to agree what the agreement on each issue was, in the first place.
A light approach could be to mark each case as "noticed" (= notified but no action from the author expected), "to be changed" and so on. This would mean all attendees also are in sync about what really is going to be done on a single incident.
Documenting too much is sure to make code reviews tedious and burocratical. Which way is best would also have to do with the kind of the project (banking/space vs. something not-so-critical) and whether the people work in the same company or if it's a subcontracting review (= money will be paid if/when it passes).
In huge projects, documenting the review becomes necessary. What if sometimes the changes you make might have to be reverted back to some old code? there might be a bug in the new code and there might be a need to revert back to the old code. It's always better to document it. I don't buy your argument saying it could be used improperly. People who intend to use it improperly have numerous other ways of achieving the same.
For me, the purpose of documenting code review is only to agree on a todo list. It may be formalized by putting items of this todo list in the issue tracking database.
A code review serves two main purposes:
The first can benefit from documentation:
"We noticed that feature A often uses X and Y when it would be better to use Z - keep this in mind for future similar features".
The second can typically not:
"Tom screwed up again"
Code reviews SHOULD be documented. Many people have selective memory and will conveniently forget some forms of feedback especially when it is easier to bury than it is to rewrite.
There are numerous code review tools to help you write, document and track the code review. Could be as simple as a javadoc doclet reading review annotations and producing text file with the review comments which can be checked in in your SCM. More complex solutions could be backed up with a database and let you even configure workflow on how to review.
All depends on how large (team size, code base, change lists, etc.) your project is. The bigger the project, the greater the need for good code review.