Code Review

Code review is an integral part of the software development process, where another developer or a group of developers examine the code to ensure its quality, maintainability, and accuracy. It involves a systematic process of reviewing the code and analyzing it for design, functionality, complexity, and adherence to style guides, among other factors. In this blog post, we'll discuss how to conduct a code review, including what to look for while reviewing and tips for receiving and giving reviews. By the end of this post, you'll better understand how to conduct effective code reviews and improve the overall quality of your codebase.

Working alone on projects can be challenging, but I still recommend following these practices if you want to have fewer bugs and a consistent codebase. The strategy that I use is to review the code the next day, that way, I get distance from the task and get back to reviewing the code with a fresh mind. But the best recommendation is to let another person review your work.

Before getting into the guidelines of how to review code effectively, it's good to keep in mind that all resources written in this blog post were done by research and selecting what high-performance teams are doing.

How to do a code review

• Review less than 400 lines of code;
  • According to a SmartBear study of a Cisco Systems programming team, the developers should review no more than 200 to 400 lines of code (LOC) at a time, citing that the brain can only effectively process so much information at a time.
  • Say if a team decides to go beyond the 400 LOC limit, the ability to find defects is highly affected.
• If it's a FE task, you should check if the PR has screenshots or videos of the changes;
• You must look at every line of code that you have been assigned to review;
• Read the feature description thoroughly to check if everything is implemented;
• You must comment on any issue;
• Each project must have a PR template and use the GitHub feature of PR templates to add the section Checklist to it;
• Run the code and use it as the end user would. Double check requested feature’s description;
• Changes should have a narrow, well-defined, self-contained scope that they cover exhaustively;
• If you are not in the middle of a focused task, you should do a code review shortly after it comes in;

What to look for while reviewing

• Design: Is the code well-designed and appropriate for your system?
• Functionality: Does the code behave as the author likely intended? Is the way the code behaves well for its users?
• Complexity: Could the code be made simpler? Would another developer be able to easily understand and use this code when they come across it in the future?
• Tests: Does the code have correct and well-designed automated tests?
• Naming: Did the developer choose clear names for variables, classes, methods, etc.?
• Comments: Are the comments clear and useful?
• Style: Does the code follow the style guide defined for the project?
• Documentation: Did the developer also update relevant documentation?

Speed of Code Reviews

There is one time when the consideration of personal velocity trumps team velocity. If you are in the middle of a focused task, such as writing code, don’t interrupt yourself to do a code review. Research has shown that it can take a long time for a developer to get back into a smooth flow of development after being interrupted. So interrupting yourself while coding is actually more expensive to the team than making another developer wait a bit for a code review.

• Why Should Code Reviews Be Fast?
  • The velocity of the team as a whole is decreased
  • Developers start to protest the code review process
  • Tasks can be delayed
• If you are not in the middle of a focused task, you should do a code review shortly after it comes in.
• One business day is the maximum time it should take to respond to a code review request (i.e., first thing the next morning).

Cultivate Healthy Reviews

Code reviews are powerful means to improve code quality, establish best practices, and spread knowledge. However, they can come to nothing or harm interpersonal relations when they are done wrong. Hence, it’s important to pay attention to the human aspects of code reviews understanding they require a certain mindset and phrasing techniques to be successful.

In general, it is important to be courteous and respectful while also being very clear and helpful to the developer whose code you are reviewing. One way to do this is to be sure that you are always commenting about the code and never commenting about the developer. You don’t always have to follow this practice, but you should definitely use it when saying something that might otherwise be upsetting or confrontational. For example:

• Bad: “Why did you use threads here when there’s obviously no benefit to be gained from concurrency?”
• Good: “The concurrency model here is adding complexity to the system without any actual performance benefit that I can see. Because there’s no performance benefit, it’s best for this code to be single-threaded instead of using multiple threads.”

General tips

Talk about the code, not the coder

• Wrong: “You’re requesting the service multiple times, which is inefficient.“
• Better: “This code is requesting the service multiple times, which is inefficient.“

Ask questions instead of making statements. This is a soft way to give feedback and discover the author’s intention.

• Wrong: “This variable should have the name ‘userId’"
• Better: “What do you think about the name ‘userId’ for this variable?“

Always refer to the behavior, not the attributes of the author.

• Wrong: “You are sloppy when it comes to writing tests.“
• Better: “I believe that you should pay more attention to writing tests.“

Accept That There Are Different Solutions

• Wrong: “I always use fixed timestamps in tests, and you should too.“
• Better: “I would always use fixed timestamps in tests for better reproducibility, but in this simple test, using the current timestamp is also ok.“

Praise! Don’t forget to express your appreciation if you have reviewed good code.

• Wrong: “Most of your code looks good, but the method calc() is too big.“
• Better: “I really like the class ProductController. It has a clear single responsibility, is coherent, and contains nicely named methods. Good Job!

Tips on receiving reviews

• Making mistakes is accepted, and admitting them is desired;
• You != Your code;
• Be humble. You are not perfect, and you can also improve.

Tips on commenting

• Is it true? (opinion != truth)
• Is it necessary? (avoid nagging, unnecessary comments, and out-of-scope work)
• Be kind and thankful;
• Mind the IKEA effect. People value things that require assembly more than pre-assembled things. This means you might place a too high value on your own code, for example, preventing its replacement by an external library;
• Mind the OIR-Rule (Observation, Impact, Request) of giving feedback. Describe your Observation (this method is too large), explain the Impact (it doesn’t follow the pattern of small methods the project has), and make a Request (could you please break it up on the part that saves the file?)
• Explain your reasoning;
• Balance giving explicit directions by just pointing out problems and letting the developer decide;
• Encourage developers to simplify code or add code comments instead of just explaining the complexity to you.
• Use I-Messages: "I suggest...", "I think...", "I believe...", "I would...", "It's hard for me to...", "For me, it seems like...", "The way I see it...";

Code review is an essential step in the software development process that involves examining code for its quality, maintainability, and accuracy. To cultivate healthy code reviews, it's important to pay attention to the human aspects of the process and encourage developers to simplify or add comments to their code. By following the guidelines outlined in this blog post, developers can improve the overall quality of their codebase and establish best practices for future projects.

References:

• How to do a code Review
• Code review guide-line for humans
• Code Review
• ChatGPT