Code Review: Types, Organization, and Best Practices

1. Types of Code Reviews

There are several types of code reviews, each with specific objectives. Here are the main ones:

a. The Ad Hoc Code Review

This review is informal and is usually performed on minor changes. The developer may ask one or two colleagues to review their code, with no strict procedure in place. While this type of review is quick, it can lack rigor if the reviewers are not attentive.

b. Pull Request (PR) Mode Code Review

This is the most common method used with GitHub and GitLab. A pull request (PR) is submitted when a new feature, bug fix, or improvement is ready. Then, one or more developers review the PR before merging it into the main branch.

c. Synchronous code review

This is a real-time review, often involving pair programming or screen-sharing tools. Although this approach is useful for critical or urgent projects, it requires both parties to be available at the same time.

d. Automated code review

Tools such as SonarQube and GitLab CI/CD pipelines automate certain checks, such as testing, linting, and security analysis, to detect basic problems before human review.

In addition, artificial intelligence solutions (such as GitHub Copilot, CodeRabbit, and AI Code Review Action) now partially automate code review. Though these tools can speed up the identification of defects or poor practices, their recommendations should be interpreted with caution. They are not a substitute for the expertise of an experienced developer. Finally, it is important to be mindful of data sovereignty issues. Using external services may expose source code and raise confidentiality or regulatory compliance issues.

2. Organizing your Code Review

An effective code review requires rigorous organization. Below are some tips for organizing this process on GitLab and GitHub:

a. Define a clear process

Each team should establish clear rules regarding when a pull request is ready for review, who should review it, and how many approvals are required before merging. For example, one rule could be: ‘Each PR must be reviewed by at least two team members and validated by automated tests.’

b. Divide the pull request into small portions

Large pull requests can be difficult to review properly. For this reason, it is recommended that features or fixes be split into manageable chunks, each associated with a separate PR. This allows reviewers to focus on specific changes and provide higher-quality feedback.

c. Limit pull requests to necessary changes

Only changes directly related to a task or ticket should be included in a pull request. Adding code cleanups or other improvements can complicate the review process and obscure the intentions behind the changes.

3. How to Use Templates for Pull Requests

Both GitLab and GitHub allow you to use templates to standardize pull requests and streamline the review process. Here's how to set them up:

a. Creating a Pull Request Template on GitHub

First, create a file called PULL_REQUEST_TEMPLATE.md file in the .github/ directory of your repository.

This file can contain predefined sections such as:

## Description
Please provide a brief description of the changes.

## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactoring

## Tests
- [ ] Are unit tests present?
- [ ] Is the documentation up to date?

b. Creating a PR Template on GitLab

1. In GitLab, PR templates are located in the .gitlab/merge_request_templates/ directory.

2. As with GitHub, you can create a useful structure to guide contributors:

## Purpose of this MR
Summarise the changes and their purpose.

## Related links
– JIRA or GitLab ticket: [Link]

## Checks
– [ ] Do all tests pass?
– [ ] Has the code been reviewed?

These templates guarantee that PRs include all the necessary information for a thorough review.

4. Create a Checklist

Checklists are an excellent way to ensure that every aspect of the code has been considered before merging. Below is an example of a checklist to include in PR templates:

Items to check in a checklist include:

• The code follows the team's style conventions.

• All new files include the correct license headers.

• New features are covered by the appropriate tests (unit or functional tests, as applicable).

• The code has been tested in development and simulated production environments.

• No obsolete, unmaintained, or abandoned dependencies have been introduced.

• No deprecated syntax or APIs have been used.

• Technical documentation has been updated as necessary.

• The impact of the changes on performance has been assessed.

5. Automate Certain Steps with GitLab CI/CD

With GitLab, you can integrate CI/CD pipelines to automate certain PR validation steps. This enables you to run tests, perform code quality checks, and conduct security analyses before human review begins. For example, you can configure a pipeline to run unit and functional tests.

• Run unit and functional tests.

• Run linting tools to check style conventions.

• Use tools such as SonarQube to detect vulnerabilities or code smells.

Conclusion

Code review is a key practice for ensuring code quality. GitHub and GitLab offer tools and features that, when used properly, can help organize this process efficiently and rigorously. Using PR templates, creating checklists, and automating steps with CI/CD pipelines can improve your team's productivity, reduce errors, and promote knowledge sharing that benefits everyone.

Organization and communication are key to conducting a successful code review. Adhering to best practices on these platforms contributes to more robust development processes and higher-quality code.