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 to a review to indicate that they are participating in the review and sharing responsibility for the review.
  • Reviewers can add comments to a changelist, to a specific file in a changelist, or to a specific line in a file, 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.
  • Project branches with assigned moderators limit review approval to one of the moderators.
  • Reviews spanning multiple project branches with assigned moderators, limit review approval to one moderator from any one of the branches by default.

    • Note

    Swarm can be configured to require that one moderator from each branch must approve the review. For more information about moderator behavior, see Moderators.

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

Workflow

By default, Swarm's code review workflow is basically advisory in nature with very few restrictions imposed on the code review workflow. However, Swarm does provide a number of 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. For more information about moderators, see Moderators.
  • Administrators can optionally configure Swarm to prevent reviews with open tasks being approved or, approved and committed, see Disable approve for reviews with open tasks.
  • Workflow: on by default:
    • Global workflow rules can be configured to enforce a minimum code review workflow on the entire Helix Core Server. For more information on global workflows, see Workflow basics.
    • Global workflow rules can be configured to enforce a minimum code review workflow on projects, and branches that don't have an associated workflow. For more information on global workflows, see Workflow basics.
    • Individual workflows can be configured by users and can be associated with projects, and branches to enforce that code review workflow on them. For more information on workflow, see Workflow basics.

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.