The Art and Science of Code Reviews

Ivan Novak - Aug 7 '23 - - Dev Community

Let's be real: Code reviews aren't the most exciting task on a developer's to-do list.

The question is, what ingredients go into making a good code review? And, how do we make it suck less?

Firstly, let's clarify what a code review is. It's not just about nitpicking at someone else's code or pointing out every missing semicolon. It's a chance to learn and grow, to improve the quality of the code, and to build team unity. It's like a book club, but for code. We're all here to enjoy the story, discuss the plot twists, and maybe, just maybe, make it a little bit better. 

A good code review is an art. The reviewer is like a sculptor, chipping away at the raw block of code to reveal the masterpiece beneath. But it's also a science. It requires a methodical approach, a clear understanding of the code's purpose, and an eye for detail. 

"A good code reviewer doesn't just find bugs; they also foster learning, maintain code quality, and promote team unity."

So, how can we achieve this delicate balance of art and science? 

  • Learning: Code reviews are an opportunity to learn from each other. Be open to feedback and ready to share your knowledge.
  • Quality: Maintaining code quality should be the top priority. Look for bugs, style inconsistencies, and potential improvements.
  • Unity: Code reviews are a team sport. Be supportive, constructive, and respectful to your teammates.

How NOT to do a Code Review

1. The Nitpicker 

Code reviews are not about playing 'Spot the Typo' or 'Find the Missing Semicolon'. Yes, clean code matters, but remember, we're coders, not grammar teachers. It's about the code's functionality and maintainability over minor style inconsistencies. 

"Code reviews aren't about nitpicking; they're about nurturing quality and collaboration."

Linting should be able to be done locally without The Nitpicker. 

2. The Novel Writer 

Ever got a review longer than the code itself? You're not alone. Code reviews should be concise and to the point. It's not about flexing your vocabulary muscles or delivering 'War and Peace' in comments. 

PR on a PR? Nope. Be helpful, don't do the work for them.

3. The Silent Type 

Code reviews are a two-way street. If you're giving a review, make sure to provide constructive feedback. And if you're on the receiving end? Don't respond with silence. Ask questions, provide explanations, engage! 

LGTM is not helpful. Dragging feet on the PR Issue log is also inappropriate.

4. The Dictator 

Code reviews aren't a power play. It's not about enforcing your personal style or preferences but about maintaining code quality and consistency. Remember, code review is a democracy, not a dictatorship. 

There is a reason why linting and quality metrics can be standardized and applied in the pipeline. What makes code in style and up to quality? It's defined. Want to change it? Submit a PR. The Dictator is counterproductive.

5. The 'Always Negative' Reviewer 

While it's important to highlight issues, don't forget to acknowledge what's done right. A good review isn't just about pointing out bugs, it's about fostering learning and promoting team unity. It's a balance. 

Let's extract this to an interface and inject it. Move toward Dependency Inversion.

... goes nicely with ...

Nice use of Liskov!

Why Code Reviews Matter

Before we delve into the nuances, let's establish the basics. Code reviews are a critical component of the software development process. They serve multiple purposes:

  1. Bug Identification: A second pair of eyes often catches what the first pair missed.
  2. Knowledge Sharing: Reviews disseminate knowledge about codebase changes, ensuring that no single person becomes a silo of information.
  3. Code Consistency: They ensure the code aligns with the team's coding standards and practices. Great code looks like it was all written by one person. 
  4. Team Cohesion: Believe it or not, reviews can be a bonding experience, bringing developers closer through collaboration and mutual learning.

The Science: Technical Mastery in Reviews

Code reviews aren't just about spotting errors. They’re about ensuring the code is of the highest quality. Here are some technical aspects to keep in mind:

  1. Understand Context: Ensure you comprehend the problem the code is trying to solve. Sometimes, the issue isn't with the code itself but with its alignment to the requirements.
  2. Check for Performance Issues: Review for any potential bottlenecks or inefficient loops that could hamper performance.
  3. Security Scrutiny: Keep an eye out for potential security vulnerabilities, such as exposed sensitive data or unchecked user inputs.
  4. Code Modularity and Cleanliness: Code should not just work; it should be clean and modular for future maintainability.

The Art: Fostering a Collaborative Review Culture

Beyond the cold logic of code, there’s a more subtle, artful side to code reviews. This deals with the human element, and it’s crucial to a successful review process.

  1. Feedback Framing: Always frame feedback constructively. Instead of saying, "This won't work," consider, "Could this approach be optimized further?" That Socrates guy was onto something.
  2. Encourage Questions: Promote a culture where asking questions during reviews is welcomed and encouraged.
  3. Recognize and Appreciate: Acknowledge good code and innovative solutions. A bit of positive reinforcement goes a long way.
  4. Balance Critique with Empathy: Understand that every piece of code has effort behind it. Be respectful in your feedback, emphasizing improvement rather than criticism.

Tools and Best Practices

The modern developer isn't just armed with knowledge but also a suite of tools to aid in code reviews.

  1. Version Control Platforms: Tools like GitHub and Bitbucket provide integrated code review tools, making it easier to comment, discuss, and track changes.
  2. Automated Testing: Before diving into a review, automated tests can help identify glaring issues. Tools like Jenkins or Travis CI can help in this regard.
  3. Linters and Formatters: Tools like ESLint or Prettier can automatically catch and fix style inconsistencies, reducing the manual overhead in reviews.
  4. Automated Quality and Security Analysis: Tools like SonarQube can highlight areas of cyclomatic and cognitive complexity. Beyond that, they can be configured to fail the pipeline so as to de-personalize the feedback and ensure all team members contributions are held to the same standards.

The Symphony of Code Reviews

Code reviews are a symphony of technical precision and human collaboration. When done right, they're not just a step in the development process but an enriching experience that elevates the entire team's skillset and cohesion.

To truly master code reviews, we must walk the delicate line between scrutinizing the code's science and understanding the art of human collaboration.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .