Code Review: Complete Definition and Guide

What is Code Review?

Code review is the process by which one or more developers systematically examine code written by a colleague before it is merged into the main codebase. This practice, which has existed since the early days of computing (Fagan's code inspections date back to 1976), has been modernised and democratised by platforms like GitHub and GitLab through pull requests (or merge requests).

A code review is not limited to looking for bugs. It encompasses verifying code readability, adherence to team conventions, appropriateness of the chosen architecture, edge case coverage, and documentation quality. It is also a moment for exchange and learning between developers, where more experienced ones share their expertise and more junior developers bring fresh perspectives.

Why Code Review Matters

Code review is one of the most effective practices for improving software quality. Studies show it detects between 60% and 90% of defects before they reach production.

• Early bug detection: An external eye spots errors the code author can no longer see, blinded by their own logic. The most costly bugs are those discovered in production; review intercepts them upstream.
• Knowledge sharing: Every review is a bidirectional learning session. The reviewer discovers parts of the code they didn't know, and the author benefits from different perspectives.
• Codebase consistency: Review ensures code respects conventions and patterns established by the team, maintaining a readable and maintainable codebase.
• Reduced bus factor: If every piece of code is seen by at least two people, losing a team member does not create a knowledge black hole.
• Architectural quality: Review is the last safeguard before integration to verify that technical choices align with the project's overall architecture.

How It Works

The code review process fits within the team's Git workflow. The developer creates a feature branch, makes their changes, then opens a pull request (PR) on GitHub or a merge request (MR) on GitLab. One or more reviewers are assigned (automatically or manually) and examine the changes.

The reviewer goes through the diff line by line, leaves comments on questionable passages, suggests improvements, and approves or requests changes. The author responds to comments, makes necessary adjustments, and updates the PR. Once approved, the PR is merged into the main branch.

At Kern-IT, code review is mandatory for all code going to production. Every PR must be approved by at least one other developer. We have established clear conventions: the PR must be small enough to review in under 30 minutes (ideally fewer than 400 changed lines), the title must be descriptive, and tests must pass before review. We use labels to indicate urgency level and change type (feature, bugfix, refactoring).

Concrete Example

During the development of a full-text search feature on a Wagtail project, a junior developer submitted a PR that implemented search by performing a SQL LIKE query on every text field of each page. The review revealed several problems: disastrous performance on a large volume of pages, no pagination, and SQL injection vulnerability.

The senior reviewer suggested using Wagtail's built-in search backend, which leverages PostgreSQL's full-text indexing. This approach was not only more performant but also simpler to maintain. The junior developer learned about this feature and was able to refactor their PR in one hour. Without code review, this problematic implementation would have gone to production and caused performance issues as soon as the page count grew.

Implementation

1. Establish review guidelines: Document what the team expects from a good PR (maximum size, description, required tests) and what the reviewer should check (logic, style, security, performance).
2. Configure the tools: Enable branch protection on GitHub/GitLab to require at least one approval before merging. Configure notifications so reviewers are alerted quickly.
3. Train the team: Learn to give constructive feedback ("What do you think of this alternative?" rather than "This is poorly written") and to receive comments without taking them personally.
4. Limit PR size: Encourage small, focused PRs. A 1000-line PR will be skimmed; a 200-line PR will be reviewed in depth.
5. Automate what you can: Linting, formatting, and security checks should be automated in CI so reviewers focus on logic and architecture.
6. Measure and adjust: Track average review time and number of comments per PR. Too long means PRs are too big; zero comments means superficial reviews.

Associated Technologies and Tools

• GitHub Pull Requests: GitHub's integrated review tool with inline comments, code suggestions, and approval workflows
• GitLab Merge Requests: GitLab's equivalent with similar features and native CI/CD integration
• Ruff / Black: Automatic formatting and linting for Python, eliminating style discussions in review
• SonarQube: Static code analysis to automatically detect quality and security issues
• Conventional Comments: Convention for structuring review comments (suggestion, question, nitpick, issue)

Conclusion

Code review is one of the highest-return investments in software engineering. It improves code quality, strengthens team skills, reduces bus factor, and prevents costly bugs. At Kern-IT, no line of code goes to production without being reviewed by a peer. This discipline, combined with automated linting and testing, enables us to maintain a healthy and evolvable codebase over the long term. If you don't yet practise code review, it's the first habit to establish: its impact is immediate and lasting.