How to use Google Code's code review tool| New! Assigned reviews. See below. |
"Open source" literally means that the source code of each project can be accessed by project members and other users. It is a tradition in many open source projects to frequently review the source code as changes are made. This is a good practice because it helps catch software defects that might be hard to discover through testing and debugging. Code reviews also help the members of the project team stay aware of each others' changes and aligned with the goals of the project. Also, participating in code reviews can be a great way for people to improve their software development skills. Project hosting on Google Code offers a code review feature that is integrated into source code browsing. It currently supports reviewing code after that code has been committed to the repository. Reviewing committed code naturally leads to discussions about further commits for further improvements. Review commentsYou must be logged in to enter a code review comment. By default, the owners and members of a project are the only people who may leave review comments. However, a project owner may choose to disable all reviews, or allow non-members to do reviews as well. Review comments are made in the context of a source code revision or an assigned review issue. If you view the list of recent source code changes and drill into the detail page for one revision or assigned review, you will see any review comments entered there by other users. If you navigate to a different revision, you will see a different set of comments, if any have been entered there. Review comments are kept as part of the history of the project: if a problem is found during review of one revision, it might be fixed in a later revision of the code, but the comment that pointed it out will always remain on the earlier revision. Review comments have three parts, and each part is optional: - A set of line-by-line comments that are made on individual lines of any source code file
- A general comment on the entire source code revision
- A score: positive, neutral, or negative
To leave line-by-line comments, browse any source code file and then double-click on a source code line. You will see a text field where you can enter your comment on that line. For example, if you notice a while-loop that can become an infinite loop in certain situations, you could comment on the line that has the while-loop condition. Line-by-line comments are drafts until you publish them. That allows you to revise comments as you work through the review. For example, you might notice that the infinite loop situation is prevented by some other invariant condition, so you might revise or delete your initial draft. Line-by-line comments can also be entered on the side-by-side diff page. You can double-click on any line of the old or new file to leave a comment there. You will most often want to leave comments on the new versions of modified lines on the right-hand side, but you may also decide to leave comments on the old version, or on unchanged lines that are indirectly affected by the change. All comments made while on the diff page are part of your review of the new revision, even if you make them on the left-hand side. Both the source file browsing page and the diff page offer a drop-down menu that allows you to navigate among the files modified in a given revision. You will normally want to look at all files in a revision before publishing your comments. Once you have entered and revised all your line-by-line comments, click the "Publish your comments" link to go to the revision details page. There you will see all your draft comments and have the opportunity to enter a general comment and to summarize your feelings about the revision with a score. Once your comments are published, you can no longer edit them, but you can delete or undelete them if needed. Assigned reviewsAssigned reviews are a way for teams do work on a branch and then review everything done on that branch before it is merged. Unlike the open-ended review comments that can be made on any revision at any time, assigned reviews are tied to a code review issue in the issue tracker and they include all changes made to a specified branch. That issue can be assigned to a specific project member as a way of requesting that he/she spend time doing the review, although others are still free to comment on it. You can request a review by clicking the "Request Code Review" link under the "Source" tab. All comments made as part of an assigned review are only visible in the context of that review. Open code review issues are shown in the the issue tracker and also at the top of the source code changes page. When the reviewer is done, he/she can close the issue by setting its status to "Done" or any other closed status value. For example: - A developer creates a new branch with svn cp trunk branches/hot-new-stuff.
- The developer writes, tests, and commits several changes to that branch.
- The developer clicks "Request Code Review" and fills in the username of a teammate, a description of what the reviewer should look for, and the path to the branch.
- The reviewer gets a regular issue notification email about the new code review issue.
- The reviewer follows a link from the issue to the branch page and sees a summary of all the work that has been done on the branch and can view diffs.
- The reviewer enters review comments, publishes them, and continues the discussion with the developer.
- The developer may make additional changes to the code based on feedback from the reviewer.
- When the reviewer is satisfied, he/she sets the review issue status to "Done" and the issue is closed.
- The developer would then merge the work done on the branch into /trunk.
Commit log syntaxReviews can also be assigned via commit log messages using a simple command syntax. (Project administrators must enable this option via the Administer/Source page.) Commands consist of a line containing only the phrase "new review:", optionally followed by 1 or more option lines and ending with a description. For example: new review:
owner: mike.j.parent
labels: Priority-High, MajorFeature, HotStuff
A large set of changes to the core library. One review request is allowed per log message. The "new review" line must be preceded by a single blank line, or must be the very first line in the message. The description consists of the first non-option line until the end of the log message. Default values from the "Review request" issue template will be used for any unspecified options. Valid review request options are: - owner
- cc
- summary
- status
- labels
- branch
Examples: Fixed bug causing File::Open method to return an incorrect value.
new review:
owner: steve.mckay
cc: jrobbins, mike.j.parent
summary: Review proposed library changes
labels: ReadyForReview, Priority-Medium
branch: /branches/mikes-changes
Please review my proposed changes to the File class.
Pay extra attention to my changes to File::Open. Updated Acme library to v1.0
new review Stars and notificationsWhen one user publishes his or her review comments, an email notification is sent to all other users who have starred that revision or assigned review. A project owner may also configure the tool to send a notification of every review comment to one address, which would normally be a mailing list. Individual users may opt out of these notification messages by using the Settings tab of your Profile page. Users star a revision in three ways: - The author of each revision automatically stars that revision
- Users may click the star icon in the source changes list or revision detail page
- When submitting a comment on a revision that is not already starred, a checkbox offers to star the revision
If you receive a code review comment notification email, and you want to respond, you can visit the web site to leave more comments. Alternatively, you can discuss it on your project mailing list. Replying to the notification email itself does not record your response in the code review tool. Keyboard shortcutsOn the revision detail page: | Key | Action | | j | Select next changed file in revision | | k | Select previous changed file in revision | | o | Open the diff view on the selected file |
On the source code diff page or source file browsing page: | Key | Action | | j | Select next changed file in revision | | k | Select previous changed file in revision | | n | Go to the next diff chunk or comment | | p | Go to the previous diff chunk or comment | | u | Go up to the revision detail page | | r | Go up to the revision detail page and scroll to the review comments form |
Administrative optionsProject owners may use the "Administer" tab and the "Source" subtab to configure: - The types of users who may enter code review comments
- An address where all code review notification emails should be sent
Effective code reviewsIt is important to keep in mind that code reviews are supposed to help advance the project. The best comments are ones that can be acted on to improve the code. Some things to keep in mind: - Code reviews are about the code, not the author. Everyone makes mistakes sometimes.
- Use a written style guide to resolve matters of source code style. It's easiest if everyone just follows the style guide.
- Make a shared checklist of things to look for in all reviews, e.g., memory allocation conventions and input validation.
Requesting ReviewsAsk for 1 to 2 reviewersWhile it may seem more effective to cast a wide net to find a reviewer by requesting an entire mailing list or large sub-group to review a change, it actually tends to reduce the response rate. The more people included on a review, the more everyone thinks someone else will get to that review before they do. In the end, your review request is more likely to be ignored. If you must have multiple reviewers, make it clear what the expectations are for each reviewer. Either noting the expectation in the review request, or contacting them through some other channel can be effective. Find a reviewer familiar with the codeFinding a good code reviewer can be a little tricky, especially if you are new to a particular project. Two ways to help narrow down good reviewer candidates are to look at the authors that have recently modified a file, using the svn log command, and to examine a file to find the last person to change related lines, using the svn blame command. One other common place to look is the AUTHORS or README files within a project. These may not be quite as relevant, but can be useful in finding a point of contact. Consider a reviewers historyWhen selecting a reviewer, consider their past review history. Some reviewers will return a response faster than others, while others may be more thorough, and there may be reviewers which cover both. Finding a reviewer who cares about the particular area of the change is important and will generally lead to faster and more helpful reviews. Warn reviewers about big changesIf you will be sending the reviewer a large change to review, warn them ahead of time and set expectations on the amount of time required and when the reviewer will have time to perform the review. Suddenly receiving a large review without notice can be received as not respecting the reviewers time. Factor time into reviewsIf your reviewer happens to be in a different time zone, be aware of the times they are likely to perform reviews. If the reviewer is multiple time zones away, sending them a review at the end of a coding session can work well since they can complete it before you return the next day. In the same sense, sending it earlier in the day to that same reviewer can result in a longer wait time for the review than someone in the same time zone. Request smaller reviewsIf a change can be easily broken up into smaller changes, it will make it considerably easier on the reviewer to send multiple small changes than one large one. Don't split up changes if they are one cohesive change even if it is large.
|
Sign in to add a comment
Looks Good To Me.
Isn't it better to review code before it actually goes into the project? That's what we do.
ondrej.certik: Different projects work in different ways. Many open source projects do post-commit reviews, many do pre-commit reviews, and many do some of each. The classic open source model is to allow project members to commit and then review their work post-commit, while non-members suggestions are reviewed before the change is eventually committed by a member.
Stay tuned for more ways to do reviews in the future. Or, use your Google Code repository with an external review tool like these.
ondrej: actually, with a decent revision control system, you can do both, simply have a pending-review branch and a master branch.
pre-commit reviews usually stop people from contributing. Some changes are so complex that require several steps and it's convenient to examine each step separately after all of them already committed.
It would be great to be able to create an issue from any review comment. Such an issue could contain a link to web presentation of revision-file-line and perhaps the text of comment.
I would like to add a review comment for code.google.com. On the page http://code.google.com/p/fbug/issues/detail line 605 is written: setInterval("checksubmit();", 700); The line causes the javascript compiler to run pointlessly every 700 ms. The line should read: setInterval(checksubmit, 700); then the function is called that has already been compiled.
Can the review comments be stored in the svn repo in some editable manner? What I like about the Google Code wiki is that content can be edited either in the browser or via my editor of preference and committed to svn. That also means I have a local copy I can look at when offline. There are times when a nice-looking GUI interface is useful, and times when I want my editor's power features and don't want to type into a limited box in a web browser.
this is beyond cool. thanks jrobbins and team!
it would be better if comment is not displayed as inline. Comments better to popup as a bubble while cursor is on it.
Much appreciated. My LG Vu Cu920 is all I had to work with. No PC, no Mac, and I have yet to buy a data cable. Ill be without a PC for a bit due to another Limewire crash by my wonder younger sibling. Anyways, thank you!
wooo， coool
Can it record my commit time on the source code ?
it nice but i did not get proper information ?
One question, How I can create wikis in other folders, for example in wiki/test/esto.wiki?
I love this feature. It's very useful for reviewing the projects my summer students are working on. Thanks!
One thing I'd love to have is a keyboard shortcut to go to the next/previous revision from the revision detail page. I tend to review the commits in batches so this would make it easier to navigate. To me 'h' for previous and 'l' for next are obvious choices, since 'j' and 'k' are already used. But any shortcut is fine with me...
Very nice!