NetarchiveSuite|
Size: 13762
Comment:
|
Size: 13763
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 22: | Line 22: |
| Code review takes time, of course. The actual time spent discussing the code is typically roughly the same as is spent going over the code beforehand. Follow-up can take a varying amount of time, depending on the starting quality of the code and whether significant changes have been found necessary. Some kinds of code take longer to review than others, for instance straight-forward getter-and-setter style classes go very fast, while a review of a few lines of change in a complex method can take much longer. In the start of the NetarchiveSuite project, we kept track of the time spent preparing for and executing the review (but not doing the follow-up changes to the code). The ratio of preparation time to review time varied, but there was never more than a factor 2 difference to either side, on average the two were about the same. The number of lines of code reviewed per hour (LoC/h) varied from 88 to 300, with a mean and average value of about 170 LoC/h. Later code review times were not recorded, but is likely to be slightly faster due to a better system for taking notes. | Code review takes time, of course. The actual time spent discussing the code is typically roughly the same as is spent going over the code beforehand. Follow-up can take a varying amount of time, depending on the starting quality of the code and whether significant changes have been found necessary. Some kinds of code take longer to review than others, for instance straight-forward getter-and-setter style classes go very fast, while a review of a few lines of change in a complex method can take much longer. In the start of the !NetarchiveSuite project, we kept track of the time spent preparing for and executing the review (but not doing the follow-up changes to the code). The ratio of preparation time to review time varied, but there was never more than a factor 2 difference to either side, on average the two were about the same. The number of lines of code reviewed per hour (LoC/h) varied from 88 to 300, with a mean and average value of about 170 LoC/h. Later code review times were not recorded, but is likely to be slightly faster due to a better system for taking notes. |
Background for Code Review process
The code review process was inspired by [http://satc.gsfc.nasa.gov/fi/fipage.html:NASA's ideas for code inspection]. The process has however been simplified in order to ease the transition to inspection. As the project group gains experience with inspection it is recommended that the inspection process is refined. The description focuses on code-inspection.
Purpose
We use code reviews to improve correctness and stability of our code. The main purposes of code reviews are traditionally
- to reduce the overall error rate
- to improve productivity
Another equally important effect of code-reviews is
- to distribute information about the code and establish common coding practices
Resource Usage
Code review takes time, of course. The actual time spent discussing the code is typically roughly the same as is spent going over the code beforehand. Follow-up can take a varying amount of time, depending on the starting quality of the code and whether significant changes have been found necessary. Some kinds of code take longer to review than others, for instance straight-forward getter-and-setter style classes go very fast, while a review of a few lines of change in a complex method can take much longer. In the start of the NetarchiveSuite project, we kept track of the time spent preparing for and executing the review (but not doing the follow-up changes to the code). The ratio of preparation time to review time varied, but there was never more than a factor 2 difference to either side, on average the two were about the same. The number of lines of code reviewed per hour (LoC/h) varied from 88 to 300, with a mean and average value of about 170 LoC/h. Later code review times were not recorded, but is likely to be slightly faster due to a better system for taking notes.
Review Process
A code review consists of 2 or more persons that read the code and in a structured way identify changes that will improve the overall quality of the code. Unit test are not usually included. Code review is the third phase of implementation (following unit test writing and implementation). It is normally done when the relevant part of the code is fully implemented, i.e. fulfills all the unit tests, has been sanity tested and documented. Our process for code review contain planning, review session and follow-up as described below.
Planning
- Review participants are selected (typically before coding starts), usually only two people, namely the implementor and one person from the other institution (to facilitate knowledge exchange and avoid inbreeding of ideas).
The implementor specifies the code to be reviewed (whole files or, in case of significant rework, sections of files) in the [:Code Review Process#CodeReviewOverview:Code Review Overview per Iteration]. This includes line numbers and SVN version for each file.
- The participants agree on a time to review.
The implementor sets up or extends the [:Code Review Process#CodeReviewPagePerPage:Code Review Page per Class/JSP-page] for each file, noting date, version and areas covered.
- Before the review time, each participant reads the code thoroughly, noting problems that should be discussed. These problems range from lack of white space around delimiters to serious bugs or design problems.
Review Session
This part, while central to the whole process, should not be allowed to drag on forever. If the reviewers cannot agree on how to fix a problem within a few minutes, the item should be marked as "consider how to..." rather than prolonging the discussion.
A typical review session should take no more than an hour (and most take less than that). If it takes longer, the review should be stopped and a time to continue should be agreed upon. More than an hour of straight review reduces the efficiency.
- The participants meet on the phone (only physical meeting if possible)
- Before starting check that
- Code has been Unit tested
- Functionality has been document in manuals
- If any of these are missing than the Review should be postponed.
Discuss each code item in order of appearance in the file. Those items that the participants don't agree to discard are noted by line number and with a severity tag on the [:Code Review Process#TablesFilledPageReview:Code Review Tables filled for each review of a class/JSP-page]
If flaws are found during code review, one or more persons must at the end of review be chosen to follow up on the flaws found. Usually, this should be the one who made the changes in the first place, but if the changes are large or other time constraints interfere, one of the other reviews can step on. One specific person should always be chosen per file that needs follow-up, and the choice must be noted in the [:Code Review Process#TableFilledReviewsOverview:Code Review Overview Table Filled for each Iteration].
Follow-up
- The follow-up person goes through the list of items and handles each of them. Depending on how an item is handled, the item is marked under Status on the [link Code Review Class Page paragraph].
- The follow-up person mark the file as fully reviewed on the [link review page] once all items have been handled.
- If the implementor feels the changes are significant enough to require a new review, another review cycle starts. The first review is left as-is. This rarely happens, and should only happen when design issues have been identified and resolved during the review process.
Review Pages (technical information)
There are two kinds of review pages:
- Code Review Page per Class
- that contains all reviews made on the class
- Code Review Overview per Iteration
- that contains an overview of code reviews made within an iteration
Code Review Page per Class/JSP-page
Each class/JPS-page has its own page with all code reviews and their documentation made on the specific Class/JPS-page.
Name of Code Review Class/JSP page
Each code review page is named according to the codes position in the Java project.
For classes the name is formed from the class and package name as follows
<Unique package name for class> + <Class name> + "Review"
Where each part of the name starts by upper case and continuous in lower case (as WikiWords), for example
- for dk.netarkivet.harvester.Constants (under /trunk/src/)
For JSP pages the name is formed from the JSP-page group and the JSP page name as follows
<Unique group for JSP-page > + <JSP-page name> + "JSPReview"
Where each part is of the name starts by upper case and continuous in lower case – and “-“ are skipped where letter after “-“ is written in uppercase too (as WikiWords), for example
HistoryHarveststatusJobdetailsJSPReview
for History/!HarvestStatus-jobdetails.jsp (under /trunk/webpages/)
Anchor(TablesFilledPageReview)
Code Review Tables filled for each review of a class/JSP-page
The below tables keeps the information for each review of a class/JSP-page (or parts of one). If a class/JSP-page is reviewed more than once, new sections like this get added at the top of the same page. Storing the old reviews with task, date, SVN version and lines has proven useful for tracking down problematic changes and misunderstood designs.
[:Code Review Process#TablesFilledPageReview:Date]: |
<date when the review takes place on form YYYY/MM/DD> |
[:Code Review Process#TablesFilledPageReview:Version]: |
<SVN version number> |
[:Code Review Process#TablesFilledPageReview:Lines/parts]: |
<lines/parts reviewed> |
[:Code Review Process#TablesFilledPageReview:Bugs/Feature requests] |
<link to bug(s)/Feature request(s) partly or fully resolved by change> |
[:Code Review Process#TablesFilledPageReview:Line] |
[:Code Review Process#TablesFilledPageReview:Description] |
[:Code Review Process#TablesFilledPageReview:Severity] |
[:Code Review Process#TablesFilledPageReview:Status] |
<Line number, single, serie or interval> |
<Description of review comment> |
<Must be either BR Cosmetic (follow-up not necessary), BR Minor (follow-up would be nice), BR Major (follow-up must be done) or BR Showstopper (bug should be reported) > |
<Must be either BR Ok (no further action), BR Postponed (must be done at a later stage – this must be noted in the "Done" column of the related [:Code_Review_Process#TableFilledReviewsOverview:Code Review Overview Table Filled for each Iteration], BR Rejected (will not be done at all) or BR Obsolete (????)> |
Example is HarvesterConstantsReview
Anchor(CreationCodeReviewCodePage)
Creation of New Code Review Class/JSP Page
You must use the [:Template_Code_Review_Code_Page:Code Review Class/JSP Page Template] to create a new page.
- Create new page named as described above
- Copy the text from the template in edit mode
- Insert the template it into the new review page and adjust it
If an old review page exists on another media then this link should be referenced.
Update of Existing Code Review Class/JSP Page
If the Code Review Class Page already exists then the tables for a new review is inserted in the top of the page in order always to see newest review text first.
The page may contain a link to old review pages which is placed on another media and therefore not readable for all.
Code Review Overview per Iteration
Each iteration has its own page with an overview of code reviews, author of changes and who the reviewer is.
Anchor(NameCodeReviewOverview)
Name of Iteration Code Review Overview
Each Iteration review overview page is named according to the Iteration name.
The name is formed from the iteration number as follows
"Iteration" + <Iteration number> + "ReviewsOverview"
for example
- for review overview in Iteration 33
Anchor(TableFilledReviewsOverview)
Code Review Overview Table Filled for each Iteration
The below table keeps information of reviews made on a class/JSP-page within an Iteration.
[:Code Review Process#TableFilledReviewsOverview:Class/Page] |
[:Code Review Process#TableFilledReviewsOverview:Version] |
[:Code Review Process#TableFilledReviewsOverview:Parts/lines] |
[:Code Review Process#TableFilledReviewsOverview:Task] |
[:Code Review Process#TableFilledReviewsOverview:Author(s)] |
[:Code Review Process#TableFilledReviewsOverview:Reviewer(s)] |
[:Code Review Process#TableFilledReviewsOverview:Review date] |
[:Code Review Process#TableFilledReviewsOverview:Follow-up] |
[:Code Review Process#TableFilledReviewsOverview:Done] |
<Link to code review page for class/JSP-page named with java path name, f.ex. dk.netarkivet.harvestdefinition.JobDAO> |
<SVN version of code being reviewed> |
<Lines/parts to review> |
<Reference to task caused the code changes that are being reviewed as for example a bugs, a feature request or an assignment> |
<Initials of author of changes in code> |
<Initials of reviewer in code review> |
<Date that review was held on form YYYY/MM/DD> |
<Initials of person to do follow-up on code review> |
<Must be either BR Ok (no further action), BR Ok w/postponed (no further action within this iteration, but includes postpones to be done later)> |
Example is Iteration33ReviewsOverview
Anchor(CreationCodeReviewOverviewPage)
Creation of New Iteration Code Review Overview Page
You must use the [:Template_Code_Review_Overview_Page:Code Review Iteration Page Template] to create a new page.
- Create new page named as described above
- Copy the text from the template in edit mode
- Insert the template it into the new review page and adjust it
Anchor(UpdateCodeReviewOverviewPage)
Update of Existing Iteration Code Review Overview Page
For each class/JSP-page to be reviewed, there must be added a table line describing it.
Note that the same class/JSP-page may appear several times.
Literature
Steve McConnell, Rapid Development page 73-74
[http://satc.gsfc.nasa.gov/fi/fipage.html:NASA's ideas for code inspection]