At Codacy we set high standards, and care about the quality of the code we produce. In order to provide optimal experiences for our users, we highly suggest having a process in place for code review. To help, below are my top 6 items for your code review checklist.
Why do code review?
First, let’s go over my top three reasons that those involved in the software development process should perform code review.
- Avoid bugs: the cost of a bug increases exponentially the later you catch it.
- Sharing: being subjected to a good code review is a master learning experience.
- Culture: foster a positive collaborative environment toward a common goal.
How to optimize code review
Automatic code review tools
Automatic tools such as compilers, testing libraries, linters and formatters have improved the effectiveness of code review in recent years. They do an effective job reducing heavy lifting and boring parts of the code review process.
While there may be initial setup costs, integrating these tools yields immediate returns. I suggest you seize the opportunity to use these tools.
Top 6 items for better code review
Since automation alone cannot cover all aspects of a code review below are my top six bullet points to handle the other parts:
1. Review your code first
Always review your own code first – don’t rush pressing the button to open a pull request. I suggest following a checklist to help you catch silly mistakes, typos and other distractions in order to ultimately save others time and effort. To challenge and stretch yourself it may be helpful to answer questions such as:
- Is this the correct level of abstraction?
- Is the approach the best one given the constraints?
- How would I improve this solution?
- Are there quick wins we can tackle within the scope of code change?
- Can this be broken down into smaller code changes?
2. Understand the purpose
Make sure you understand the reason why the code change exists in the first place. Is it to:
- Fix a bug?
- Add a feature?
- Change functionality?
- Improve a technical aspect?
There should be only one purpose of a code change. If you confirm that multiple reasons exist stop and ask the author if the code change can be split. Splitting code change allows you to:
- Focus on one reason
- Avoid distractions
- Review smaller chunks
- Provide cleaner and better project history
3. Read all code changes
Go through the code (without skimming) imagining the code is a novel with a story to tell. In doing so, you will surely catch typos and inconsistencies. You can think twice about the names used for variables, methods and more. Ask yourself:
- Are they descriptive?
- Are they concise?
Though naming in software is difficult, agreeing on common rules of thumb will help make it less painful. Check that the style guide rules that your code formatter cannot catch are followed.
4. Ask (and answer) questions
As a reviewer be sure to ask all the questions that come to mind. Don’t be shy, take the opportunity to learn something new!
As an author, accept all comments in the most positive and open way. Remember, there are no personal comments. Be open to listening and considering the views of others even if you have strong opinions. Explain your choices thoroughly, exhibiting little bias.
Code reviews are an incredible opportunity to learn. Asking questions will improve the experience of everyone involved. A written discussion in a GitHub comment thread can also dramatically help when someone needs to go through an old review while tracking down a bug.
The only golden rule to bear in mind in these conversations is to stay nice and kind! This Red-Hat blog post is a great summary on conducting these conversations.
5. Air control
Look at the code change from a big picture, high-level point of view. Ask yourself is it:
- Going in the right architectural direction?
- Introducing dependencies that can be avoided?
- Rebuilding the wheel and can be simplified by using external dependencies?
- Submitted to the appropriate codebase?
- Placed in the right place within the codebase?
Challenge your answers and try to think of a simpler way to tackle the problem in the first place. Think about flows in your system and verify that changes respect patterns.
6. Ground control
Zoom in to the details of the implementation:
- Is the CI (continuous integration) green and is it passing tests? If not, why?
- Are the tests covering all the edge cases?
- Are the tests covering the error cases and not solely the happy path (main control flow) of the program?
- Is the code readable, explicit and deliberate in what it does?
- Is business logic properly separated from integration?
- Are exceptions handled properly?
- Does the code use appropriate data structures?
- Do the algorithms have an excessive computational complexity?
- Are heavy resources (like DB access and network calls) used carefully?
- Are all the used operators/methods completely clear?
Keep in mind that code can hardly be perfect from all points of view. In most cases, for example, you might want to encourage readability over performance. It’s much easier to optimize correct code rather than fixing optimized but incorrect code. Avoid premature optimizations, but, be mindful and avoid evident de-optimizations. The code should be easy to substitute and change – engineer it right to the point and no more. Avoid introducing premature extension points as they increase code complexity. Refactor only after proven need, but do it thoroughly when needed.
Conclusions
While my top items may enhance the code review process for individual developers, teams and enterprises, there are many other actions and resources you may want to consider.
In addition to some of Codacy’s own resources, many articles exist on the internet about code reviews. The following particularly caught my attention:
- https://auth0.com/blog/conducting-effective-code-reviews/
- https://github.com/thoughtbot/guides/tree/master/code-review
- https://www.michaelagreiler.com/code-review-checklist/
- https://deepsource.io/blog/code-review-best-practices/
- https://medium.com/palantir/code-review-best-practices-19e02780015f
- https://blog.digitalocean.com/how-to-conduct-effective-code-reviews/
About The Author
Andrea Peruffo is a technical lead at Codacy. He has expertise in delivering any kind of software system from large scale cloud to embedded devices. He also speaks at technology events around the world.