Code review is an integral part of the software development process, especially when working with a team. It involves checking and examining source code by peers, other developers, and even automated tools to identify potential issues and ensure that quality standards are met. There are certain principles when conducting a good code review, but today, we want to dive into what a great code review entails. Read on to get to know the best practices when just beginning to learn how to conduct code reviews!
New to code review?
Let's say that you've only worked solo and you're new to code reviews: let's get into the details. Reviewing code is a process in software development where one or more developers — for example, your teammates — take a look at a specific piece of source code to ensure it meets certain standards. Code review is crucial to maintaining high code quality and ensuring that software runs smoothly. Having a fresh pair of eyes on a project is essential to catch any mistakes, potential bugs, or ambiguities. Putting it in simple terms, code review is like having a proofreader for your code.
The benefits of code reviews
Besides the obvious benefit of increasing code quality, performing a code review offers several significant technical benefits for software development and your personal growth.
First and foremost, the code review process serves the purpose of detecting potential errors, but your reviewer can also help identify performance bottlenecks, inefficient algorithms, or redundant code segments that you might not have noticed in your code.
Additionally, code reviews ensure consistency across the codebase by enforcing coding standards and best practices. Reviewers can provide feedback on code structure, naming conventions, documentation, and other quality-related aspects. All this results in cleaner and more maintainable code.
It’s also a great opportunity for learning! There's nothing like a good peer review — by engaging in code reviews, team members collaborate closely, exchange ideas and knowledge, and learn how to provide constructive feedback.
How do you do this peer code review?
So, you received your first code review requests, and you want to know how to do it properly and efficiently. And we're here to give you the best practices of the code review process!
Our conceptual code review checklist
While many large open-source projects have well-defined contribution guidelines, it's usually up to a company's processes and standards whether they follow some particular guidelines or checklist internally.
In this article, we want to focus on the conceptual side of things, those which are more universal and can apply to general effective code review practices. When performing a code review, we recommend asking ourselves these important questions:
- Are the proposed changes aligned with the methodology and practices that are already used in the project?
- Are the proposed changes clear, readable, and easily understandable?
- Is the naming convention simple and consistent with other parts of the code? Are the new folders, files, and component structures and names clear?
- Do the component and function names clearly indicate what they refer to, are, or do?
- Is the code free of changes that do nothing but weren't detected by the system (for example, invalid CSS attributes or CSS overwritten by other selectors)?
- Do the proposed changes unintentionally interfere with other parts of the application?
- Did the code pass the tests included in the pull request?
- Do the changes work as intended?
If you review code and answer no to any of these questions, it's super important to let the developer know how they can improve the overall quality of their changes. Scroll down to the section on how to approach commenting on other's code so that you and your team member can save time on working out the refinements!
And if you want to know the technicalities...
We want you to remember that technical facts and proven data will always be more important than personal preferences and opinions. When it comes to software design, you can't put it in the same category as a coding style or a matter of taste. It's all about underlying software development principles: above all else, that's what you should weigh your feedback on — not just solely your personal opinion.
While there may be valid alternative approaches to some concepts, the author should provide you with either data or solid engineering principles to support their preference. Nonetheless, it's best to stick to the well-known and tested principles of software design!
How do you write code review comments?
Finding the golden mean between being accommodating, yet strict and constructive can be hard. Here's an approach that works best for us when doing peer reviews:
- Naturally, be kind and considerate in your feedback. Focus on the reviewed code — not on the person who wrote it. We're all on the same team, and respect goes a long way!
- Always try to find a balance between pointing out problems and offering guidance. Providing direct instructions or code examples can be helpful, but remember that if the suggestion or concept is complex, you're not required to rewrite the code or prepare an improved design of the code architecture.
- Be open to a discussion! Remember that the reviewer is not the code author, so it's vital to discuss any misunderstandings. This also helps to edit the existing code later, as comments are usually available in the version control system.
- Be clear about the severity and what kind of changes you call for — whether they're required, just guidelines, or merely suggestions. This helps prioritize which comments are most important and makes sure there are no misunderstandings.
- If you don't understand a piece of written code, asking a developer to explain it can result in them rewriting it to make it clearer or encouraging them to add comments to the code itself.
- When leaving comments on the code, make sure to explain your reasoning behind them. This helps developers understand the good practices you refer to. It's also great to acknowledge and encourage things you especially liked in the code!
As a developer, how can you make your code reviewer’s life easier?
Surely you want your code to be right the first time you submit your pull request for a review, but it's not always the case. However, there are a couple of things our developers highlighted for consideration when you're the code author:
Keep it short and sweet
It can be daunting for a code reviewer to dive into a lengthy pull request, constantly switching contexts and spending hours wading through an ocean of code changes. That's why breaking down significant features into manageable parts is beneficial, ensuring that each PR contains no more than 600 lines of code. This approach not only eases the reviewer's task but also allows them to focus on specific development sections without being overwhelmed.
For example, you can split the feature implementation into different parts, such as the initial skeleton and structure (part 1), adding functionality (part 2), applying styles (part 3), and incorporating tests (part 4). It makes for an easier and better code review for all parties!
Consider the potential application performance
Some changes might result in performance issues, and it's very important to spot them early on so that you can avoid bottlenecks later in development. Consider this example: an element in a list is constantly updated with each event, and it can seriously slow down your processing time. That's when you need to prioritize performance to improve code quality.
Even small tweaks can make a big difference: for instance, using .some() instead of .filter() to find the first matching element might seem to save just milliseconds, but it's a smart practice to adopt. In larger projects, these seemingly small changes can really add up and potentially save seconds of execution time.
Don’t repeat yourself
Embrace the Don't Repeat Yourself (DRY) principle. The key idea behind DRY is to avoid redundant code by creating a generic function or module that can be reused in multiple instances. Instead of writing the same or similar code multiple times, encapsulate it into a reusable function and use it whenever needed. This approach reduces code duplication, improves consistency, makes the code review process easier, and simplifies future modifications.
Approaching novelties from the development world
Something new and fresh is always great, and when it comes to programming, novelties usually improve some processes or tedious work. However, before introducing the most recent practices in your projects, consider the potential environmental limitations. All frameworks, libraries, and syntax have their requirements, for example — the browser version. Such innovations might only work on newer versions of tools, for instance, on a newer version of Node.js compared to the one that's used in your tech stack. That’s why before considering such changes, we recommend consulting them with the development team, the project's owner, or even your tech lead.
Automated tests and code review tools
Tests are an ally to a code reviewer — whether they are universal automation tests or tests prepared for this specific added feature, it's a great practice to have them cover a piece of added code. If the tests are prepared exclusively for the feature, a code reviewer can ensure they are clear, useful, and correctly test the validity of the code.
We should also not forget the valuable assistance that external tools can provide. Tools like JSLint, ESLint, and others prove to be incredibly helpful in automating various code checks. They can take care of tasks such as validating file and package import sorting, code formatting, and following specific naming conventions. By integrating these tools into our code review workflow, we can rely on them to automatically flag potential issues, warnings, and errors. This automation boosts efficiency and ensures consistency and adherence to coding standards, which can significantly shorten the review time.
Go on – you’re ready to start your code reviews!
By now, you should have a solid base of knowledge about reviewing code written by your peers. We hope they'll be impressed by the quality of your work and that the process will be a learning experience for everyone involved!
Be sure to let us know if there’s any specific rule you discovered to be especially beneficial in improving your code review experience.
