Section 3 Code Review
Code review applies to R packages and other tools developed by our team.
Code review should be conducted by a team member who was not intimately involved in developing the code. The reviewer will evaluate the code and documentation for usability, maintainability, performance, and to ensure that it performs the task it is intended for.
Review makes sure that the code is “good enough” and better than what it replaces. It should not include adding “nice to have” features or ensure that code is 100% optimal. These sorts of improvements can be important, but should be added as “issues” to be worked on later (see the section on maintaining code).
Please consult this summary of best practices when reviewing code.
3.0.2 Open Source Tools
Code that could be useful outside of our group should generally be developed as an open source project. This allows us to give back to the open source community from which we benefit, but it also benefits us because outside collaborators can help us maintain our code. For an example, see the intervalaverage package.
For code intended to be released as open source, please use the rOpenSci Review Template and reference the rOpenSci Guide for Reviewers.
3.0.3 Internal Tools
Internal tools are not intended to be used outside of our group because they depend on group-specific infrastructure (such as the MESA database) or perform a task that is not useful outside the context of our lab. In these cases, some of the rOpenSci standards can be relaxed (such as contact information for authors) or may not make sense (such as code functioning outside of our servers).
3.1 Procedure
Code review should happen when the package is first developed or when major changes are implemented (preferably as a pull request).
To initiate a code review, create an issue in the code repository on github, and select the appropriate issue template for internal code review or external code review. Both the author(s) and the reviewer should be assigned to that issue. The reviewer can then edit the issue description (the first comment in the issue) to check off items as they are completed.
When the reviewer and author(s) agree that the review has been completed and the any modifications to the code/documentation are satisfactory, the issue should be closed.
3.2 Ticket QC
When a ticket is generated, an R Markdown file is created for use in quality checks. The analyst filling a ticket should of course check their work, but a separate analyst should always check the deliverable data (in the case of data requests) or updated tables (in the case of data updates) and document what the checks they have performed in the R Markdown file.