Code reviews

A code review is a process in which other developers can see your code and provide feedback that can suggest ways to improve the code's structure, performance, maintainability, and interaction with other code.

Benefits

Some of the benefits of code review are:

  • Enforcing coding standards: code reviews can catch code that does not meet your team's coding standards. This improves the readability and consistency of your codebase.

  • Knowledge and experience sharing: your team can help you learn to code better. This is particularly useful for developers new to the team.

  • Early defect detection: small errors can be caught before they become problems later on.

  • Code sharing: code reviews spread knowledge of the current codebase, which helps both with maintaining a mental model of the overall project, as well as defending against developer absences.

  • Better personal review: knowing that someone might catch a simple coding error often increases the review developers perform of their own code.

Swarm attempts to provide these benefits without adding onerous overhead for developers.

Facilities

Swarm provides the following code review facilities. In the list, the term author refers to the person who creates a change to be reviewed, reviewer refers to any authenticated Swarm user performing code review tasks, and required reviewer refers to a reviewer whose up-vote is required before a review can be approved.

  • Authors can request reviews, and can designate reviewers and required reviewers.

  • Reviewers can start a code review on existing changes.

  • Reviewers can add themselves a review to indicate that they are participating in the review and sharing responsibility for the review.

  • Reviewers can provide comments to overall changes or specific lines of files, using Markdown text.

  • Reviewers can vote on a review, to indicate their approval or disapproval.

  • Required reviewers can prevent a review from becoming approved until they up-vote the review.

  • Projects with assigned moderators limit review approval to one of the moderators.

  • Reviewers can mark changes as needing revision, approved, rejected, or to be archived for future consideration.

  • Reviewers can commit approved changes if necessary.

Advisory nature

Currently, Swarm's default code review workflow would best be described as advisory. Swarm provides only a few mechanisms to structure or restrict code review workflows, such as:

  • A required reviewer, which is any user designated by a review author, project member or moderator, or is any authenticated user that joins a review and makes their vote required, can prevent reviews from being approved until they up-vote the review. See Required reviewers for details.

  • Branch moderators, when configured for one or more branches in a project, prevent reviews from being approved (or rejected) without their involvement. See Add a project for details.

  • Administrators can optionally enable triggers in the Helix Versioning Engine that can enforce that submitted changes are associated with approved reviews, and can enable strict matching of the contents of a changelist to the contents of an associated, approved code review. See Perforce configuration for Swarm and Trigger options for details.

Agile development teams should find sufficient capability within Swarm to make code reviews a regular part of their workflow. Swarm's development team has been using it regularly during development of Swarm. If you have ideas and suggestions for improvement, please contact us.