Question 1

What is code review?

Accepted Answer

Code review is a quality assurance technique in which code authors ask other developers to review their code before it joins a codebase. The code review process can be informal, such as having another developer glance at work done by a colleague, or it can be a series of documented feedback and quality checks to ensure that code meets specific standards. Creating a structured process for code review can help developers perform it in a timely manner as a regular part of the development lifecycle. This is part of an extensive series of guides about software development.

Question 2

Code reviews: pros and cons

Accepted Answer

There are several benefits to conducting code reviews, including:  • Improved code quality: • : Code reviews can help to identify problems or issues with the code, such as bugs, security vulnerabilities, or performance problems. This can lead to fewer issues in the final software product and improve the overall quality of the code.; • Enhanced collaboration: • : Code reviews provide an opportunity for developers to collaborate and share ideas, which can lead to more efficient and effective development.; • Greater code readability: • : They can help to improve the readability of the code, which makes it easier for other developers to understand and work with.; • Enhanced code maintainability: • : They can help to ensure that the code follows best practices and is written in a way that makes it easy to maintain and update in the future.; • Improved learning: • : A code review can be a learning opportunity for developers, expose developers to different coding styles and approaches, and help them to learn from the experience of their peers. • Improved code quality: • : Code reviews can help to identify problems or issues with the code, such as bugs, security vulnerabilities, or performance problems. This can lead to fewer issues in the final software product and improve the overall quality of the code.; • Enhanced collaboration: • : Code reviews provide an opportunity for developers to collaborate and share ideas, which can lead to more efficient and effective development.; • Greater code readability: • : They can help to improve the readability of the code, which makes it easier for other developers to understand and work with.; • Enhanced code maintainability: • : They can help to ensure that the code follows best practices and is written in a way that makes it easy to maintain and update in the future.; • Improved learning: • : A code review can be a learning opportunity for developers, expose developers to different coding styles and approaches, and help them to learn from the experience of their peers.;However, there are also some potential disadvantages to code reviews, including:  • Time and resource constraints: • : Code reviews can be time-consuming, as they require developers to review and provide feedback on the code of their peers. This can be especially challenging for organizations with limited resources or tight deadlines.; • Personal preferences: • : Different developers may have different preferences when it comes to coding style and approaches, which can lead to disagreement or conflict during code reviews.; • Miscommunication: • : Code reviews can be prone to miscommunication, as the review process is often done remotely and may involve multiple reviewers providing feedback on the same code.; • Decreased morale: • : If code reviews are not conducted in a constructive and positive manner, they can lead to decreased morale among developers.; • Limited focus: • : A code review may not be able to identify every issue with the code, and may not cover all aspects of the code. This means that some issues may not be identified until later in the development process, which can lead to additional time and resources being spent on fixing them. • Time and resource constraints: • : Code reviews can be time-consuming, as they require developers to review and provide feedback on the code of their peers. This can be especially challenging for organizations with limited resources or tight deadlines.; • Personal preferences: • : Different developers may have different preferences when it comes to coding style and approaches, which can lead to disagreement or conflict during code reviews.; • Miscommunication: • : Code reviews can be prone to miscommunication, as the review process is often done remotely and may involve multiple reviewers providing feedback on the same code.; • Decreased morale: • : If code reviews are not conducted in a constructive and positive manner, they can lead to decreased morale among developers.; • Limited focus: • : A code review may not be able to identify every issue with the code, and may not cover all aspects of the code. This means that some issues may not be identified until later in the development process, which can lead to additional time and resources being spent on fixing them.;

Question 3

Common code review approaches and processes

Accepted Answer

Email threads When a particular piece of code is ready to be reviewed, the file is emailed to that colleague for review as soon as the workflow permits. While this approach is certainly more flexible and adaptable than traditional techniques, email threads of suggestions and disagreements can quickly become cluttered. It is also much more difficult to share code reviews with other members of the team. Pair programming A simple form of code review is pair programming. A developer writes the code and the reviewer sits down and reads the code at the same time or modifies it on the go. This process is ideal for very complex programs and allows two people to solve problems more quickly and efficiently. While this process is advantageous, the reality is that the time and effort required for pair programming is substantial. Having two or more people writing code together means fewer lines of code per developer on average. Over-the-shoulder For most developers, over-the-shoulder code reviews are faster and more convenient than pair programming. This is one of the oldest, easiest and most intuitive ways to engage in peer code review. When one developer’s code is ready, a colleague sits down at their workstation and looks at the code, and the developer can explain why they wrote it the way they did. This unofficial approach is very lightweight, but since there is no formal way to track or document the review, it can be less effective in the long term. Tool-assisted review Possibly the easiest and most effective way to review code is to use a software-based code review tool. These tools overcome many of the limitations of manual review methods. They track peer comments and proposed solutions in a clear and consistent sequence (similar to the tracked changes mechanism in word processors), allowing for asynchronous and non-local reviews. Code review tools notify the original coder when a new review comes in, and eliminates the need for physical meetings. Some tools also generate usage statistics to enable auditing of development processes, and review metrics for process improvement and compliance reporting. Learn more in our detailed guide to code review process (coming soon).

Question 4

Common features of code review tools

Accepted Answer

Code review software facilitates collaborative feedback and quality assurance processes during software development. The software provides a structured way for non-coders to review, tweak, and comment code. Key features of peer code review software include:  • Commenting: • : Allows developers other than code authors to provide feedback about code asynchronously. Developers reviewing other people's code can highlight and comment on relevant parts of the code. If multiple developers are reviewing the code in question, peer code review software can be used to group or link multiple developers' comments related to the same line of code.; • Notifications: • : Peer code review software uses notifications to inform relevant users of the progress of the code review process. The code review tool notifies peer review partners when code authors decide that their work is available for review. The software then notifies the original author when peer review is complete, allowing them to respond to the feedback.; • Prioritization: • : Most peer code review software allows reviewers to indicate the severity of comments. For example, if a reviewer finds an application-breaking bug in the author's code, they can mark it as urgent or important. This is often done through color coding and icons such as exclamation marks, to draw the author's attention to the most important suggestions and corrections.; • Standardized best practices: • : Most peer code review software allows teams to establish and edit standardized best practices and metrics. These are highlighted as references for peer reviewers to follow. Some peer code review software automatically detects code that appears to be defective and flags it for review along with a description of the possible bug.; • Metrics: • : Peer code review software provides greater visibility into team’s best practices and metrics throughout the peer code review process, supporting management and process improvement. • Commenting: • : Allows developers other than code authors to provide feedback about code asynchronously. Developers reviewing other people's code can highlight and comment on relevant parts of the code. If multiple developers are reviewing the code in question, peer code review software can be used to group or link multiple developers' comments related to the same line of code.; • Notifications: • : Peer code review software uses notifications to inform relevant users of the progress of the code review process. The code review tool notifies peer review partners when code authors decide that their work is available for review. The software then notifies the original author when peer review is complete, allowing them to respond to the feedback.; • Prioritization: • : Most peer code review software allows reviewers to indicate the severity of comments. For example, if a reviewer finds an application-breaking bug in the author's code, they can mark it as urgent or important. This is often done through color coding and icons such as exclamation marks, to draw the author's attention to the most important suggestions and corrections.; • Standardized best practices: • : Most peer code review software allows teams to establish and edit standardized best practices and metrics. These are highlighted as references for peer reviewers to follow. Some peer code review software automatically detects code that appears to be defective and flags it for review along with a description of the possible bug.; • Metrics: • : Peer code review software provides greater visibility into team’s best practices and metrics throughout the peer code review process, supporting management and process improvement.;

Question 5

Best practices for code reviews

Accepted Answer

Create a code review checklist A code review checklist is a set of predefined questions and rules that teams follow during the code review process, helping them take a structured approach to the quality checks they need before approving code in their codebase. Checklists may include:  • Readability: • : Identifying redundant or unclear comments in the code; • Security: • : Identifying weaknesses that expose the code to cyberattacks; • Test coverage: • : Identifying the need for more test cases; • Architecture: • : Identifying issues like encapsulation and modularity of the code; • Reusability: • : Identifying whether the code properly reuses components, functions, and services • Readability: • : Identifying redundant or unclear comments in the code; • Security: • : Identifying weaknesses that expose the code to cyberattacks; • Test coverage: • : Identifying the need for more test cases; • Architecture: • : Identifying issues like encapsulation and modularity of the code; • Reusability: • : Identifying whether the code properly reuses components, functions, and services;Introduce code review metrics You cannot modify someone else's code without measuring its quality. Objective metrics help determine the effectiveness of reviews, analyze the impact of changes on processes, and predict how long it will take to complete a project. Commonly used metrics include:  • Inspection rate: • : The rate at which a team reviews a given amount of code, which is lines of code (LoC) divided by total review time. If a code review takes a long time, you may need to address readability issues in the codebase.; • Defect rate: • : How often defects are identified. Calculated by dividing the number of defects by the time spent reviewing them. This metric helps determine the effectiveness of the testing process. For example, if developers are slow at finding defects, they may need better testing tools.; • Defect density: • : The number of defects identified in a given amount of code. It is calculated by dividing the number of defects by thousands of lines of code (kLOC). Fault density helps identify which components are more prone to failure than others, so more resources can be allocated to the weaker component. • Inspection rate: • : The rate at which a team reviews a given amount of code, which is lines of code (LoC) divided by total review time. If a code review takes a long time, you may need to address readability issues in the codebase.; • Defect rate: • : How often defects are identified. Calculated by dividing the number of defects by the time spent reviewing them. This metric helps determine the effectiveness of the testing process. For example, if developers are slow at finding defects, they may need better testing tools.; • Defect density: • : The number of defects identified in a given amount of code. It is calculated by dividing the number of defects by thousands of lines of code (kLOC). Fault density helps identify which components are more prone to failure than others, so more resources can be allocated to the weaker component.;Learn more in our detailed guide to effective code review (coming soon). Keep pull requests small Smaller deployments are easier to design, test, review, and merge. A common rule of thumb is that 100 lines of code is a reasonable size for a pull request, while 1000 lines is too big. The number of files a distribution changes also affects its perceived size - for example, 100 lines of change in one file is different from the same number of lines spread across multiple different files. Breaking large changes into smaller chunks is almost always possible and makes many aspects of the development process easier, code reviews included. With more practice, developers can become proficient at finding the smallest possible increment of a product. Note that feature gates or feature flags may be required to release unfinished product features alongside existing features. Foster a positive feedback culture Effective communication is difficult to master. Giving feedback on a colleague's work is challenging for most people, both intellectually and emotionally. Below is a list of suggestions for improving code review discussions:  • Always provide feedback on the code, not the author.; • Focus on the most important problems within the code, not all the problems.; • Admit that there are multiple correct solutions to every problem.; • Give objective reasons, not emotions, for a problem in the code.; • Always try to provide positive feedback. This can make it easier for the code author to accept negative feedback, and can be valuable in itself by reinforcing best practices. • Always provide feedback on the code, not the author.; • Focus on the most important problems within the code, not all the problems.; • Admit that there are multiple correct solutions to every problem.; • Give objective reasons, not emotions, for a problem in the code.; • Always try to provide positive feedback. This can make it easier for the code author to accept negative feedback, and can be valuable in itself by reinforcing best practices.;Learn more in our detailed guide to secure coding best practices (coming soon).

Question 6

Code reviews with Swimm

Accepted Answer

Code reviews are a hallmark of teams striving for high code quality and development best practices. However, They often create bottlenecks in the development process. The review process not only slows down the time it takes to ship code, it also often occupies some of the most talented and experienced developers on the team. Therefore, making code reviews more efficient can have a significant impact on a team’s velocity. Swimm is a knowledge sharing tool for code. With it, developers write in depth documents that explain how their code works or how to work with it. Swimm keeps these documents up to date as part of the CI and easily accessible. Swimm can also be used to document Pull Requests, which can help streamline the review process. Once a PR is open, a document can be generated from it. Within a few minutes, the developer can provide the context and reasoning behind the important changes in the PR, making the code review process faster and easier.

Question 7

See Additional Guides on Key Software Development Topics

Accepted Answer

Together with our content partners, we have authored in-depth guides on several other topics that can also be useful as you explore the world of software development.

Question 8

Code Documentation

Accepted Answer

Authored by Swimm  • Agile Documentation: Benefits and Best Practices ; • Documentation as Code: Why You Need It & How to Get Started; • What Is Code Documentation and How To Write It? • Agile Documentation: Benefits and Best Practices ; • Documentation as Code: Why You Need It & How to Get Started; • What Is Code Documentation and How To Write It?;

Question 9

Technical Documentation

Accepted Answer

Authored by Swimm  • What is Technical Documentation and How to Create it? ; • Get started with technical documentation writing best practices; • Essential Resources for Technical Documentation Templates  • What is Technical Documentation and How to Create it? ; • Get started with technical documentation writing best practices; • Essential Resources for Technical Documentation Templates ;

Question 10

Environment Variables

Accepted Answer

Authored by Configu  • Leveraging Environment Variables in Python Programming; • Environment Variables: How to Use Them and 4 Critical Best Practices; • Setting Docker Environment Variables: The Ultimate Guide  • Leveraging Environment Variables in Python Programming; • Environment Variables: How to Use Them and 4 Critical Best Practices; • Setting Docker Environment Variables: The Ultimate Guide ;To try out Swimm, sign up for a 1:1 demo.

Code reviews: pros and cons, approaches, tools and tips

What is code review?