Custom Code Review Templates

The Value of Taking a Template-Based Approach

Not all reviews need the same level of scrutiny. Some can be completed quickly between two people. Others may involve stakeholders from different teams reviewing code, design documents, and test plans. With templates, your team can ensure that complex reviews move through a defined process, get the required feedback, and don't become a drag on your project.

Custom templates are comprised of a few different components, which can individually be shared across templates, including:

• Custom Fields and Workflows
• Participant Rules, Groups, and Subscriptions
• Custom Review Checklists

Custom Fields and Workflows

Adding custom fields to review templates enables your team to capture information specific to your team. Often, teams use custom fields to ask questions of reviewer or authors, include links to external tools, or address compliance requirements. You can also create custom review workflows that fit whatever approach makes the most sense for your team.

Participant Rules, Groups, and Subscriptions

Templates are a great way to ensure that everyone who needs to be in on a review checks in. To set rules for required review participants, you can use participant roles. There are four standard partipants roles in Collaborator: Author, Reviewer, Moderator, and Observer. Each can be customized. For the sake of example, your team could specify that certain reviews need 1 author and 2 reviewers and 1 moderator.

Participant Groups are another way to ensure high quality reviews. If you need someone from the security team to review an architecture document, you can add the security group as a requirement for the review. When a review involving that group is created, notifications can go out and whoever has the bandwidth to partipicate can raise their hand. Groups can also be used as a way to foster mentorship, by grouping together senior engineers so they are included on reviews to share best practices and catch mistakes.

You can also subscribe individuals and groups to certain review templates. If you have a junior developer join the team, you could subscribe them to simple reviews initially so they can get their feet wet and learn how your team works. As they progress in their onboarding, they could be subscribed to more complex reviews so they can learn more of the codebase.

Custom Review Checklists

Checklists are an important part of reviews. While it might be easy to catch mistakes evident in a code change, it is harder to remember and catch what things might be omitted from the code. By building custom review checklists, your team can set an agenda for reviews and remind reviewers what things matter most. Researchers have found that using checklists in reviews translates to much more effective reviews, relative to other expectation-settings approaches.

Checklists can also be an effective way to ensure that your team has met compliance burdens and security best practices. Some teams conduct change package reviews in Collaborator and use checklists as a way to outline their cross-functional development, ensuring that static analysis and relevant tests have been run, documentation has been updated properly, and the change has received formal sign-off.