Photo by John Schnobrich on Unsplash

PR reviews, also pull request reviews, are an essential part of the software development process. They not only help in detecting errors but also significantly contribute to improving code quality and adhering to standards. A well-conducted PR review can enhance teamwork, increase code maintainability, and ensure that best practices are followed.

In this article, I share my experiences and provide insights into what I particularly value when reviewing PRs. You will learn why code styles are important, how to note best practices, and why clear communication is essential. Additionally, I will show you how direct comments in code can make the review process more efficient and why a focus on clean code is critical.

By considering these aspects, not only is the review process itself made more efficient, but the quality of the final product is also significantly improved. Whether you are an experienced developer, project manager, or CTO, this article offers valuable tips to optimize the PR review process in your team.

Observe Code Styles

Uniform code styles are the foundation for readable and maintainable code. They ensure that the code looks the same regardless of the author, thus facilitating understanding and collaboration within the team. A consistent code style is not only aesthetically pleasing but also prevents misunderstandings and eases debugging.

Definition of Code Styles

Code styles encompass various aspects of code design, such as indentation, naming conventions, use of whitespace, comment style, and structuring of functions and classes. A well-defined code style ensures that the code is uniform and clearly structured, which significantly improves readability and maintainability.

The Importance of Consistent Code Styles

Consistent code styles are important for several reasons:

• Readability: Uniform code is easier to read and understand. Developers can focus on the content rather than adjusting to different styles.

• Maintainability: A uniform style makes it easier to make changes and extensions. New team members can onboard faster when they do not have to adapt to various styles.

• Error Prevention: Consistency reduces the likelihood of errors introduced by differing styles. It is easier to concentrate on the code's logic when the style does not present a distraction.

Tools for Checking Code Styles

There are various tools that help automatically check and enforce code styles in Flutter projects. Here are some of the most well-known and effective tools:

• Very Good Linting: This tool provides a collection of linter rules specifically designed for Dart and Flutter. It checks the code for style errors and best practices and can be adapted to the specific needs of your project. Very Good Linting helps ensure consistent code styles across the project and provides clear instructions for remedying violations.

• dart fix --apply: The command dart fix --apply is another powerful tool for improving code. It analyzes the code and suggests automatic corrections to align with Dart’s style guidelines and best practices. Applying these corrections results in cleaner and more consistent code.

• Formatter: The built-in code formatter in Flutter ensures that the code is automatically formatted according to the specified style guidelines. This relieves developers from manually adjusting the code and ensures that the code remains uniform and readable.

• CI/CD Integrations: By integrating code style checks into continuous integration (CI) and continuous deployment (CD) pipelines, you can ensure that only code compliant with the defined style guidelines is included in the main project. Tools like GitHub Actions or Bitbucket Pipelines can be configured to run linters and formatters before code is merged into the main branch.

Using these tools significantly contributes to the consistency, readability, and maintainability of code in Flutter projects. By automating and enforcing code styles, you can substantially improve the quality and consistency of your code.

Note Best Practices

Best practices are proven methods and techniques that have been shown to be effective and efficient in software development. They help write high-quality, maintainable, and scalable code. In PR reviews, it is crucial to recognize and note best practices to continuously improve code quality.

What Are Best Practices?

Best practices encompass a wide range of techniques and principles used in software development to address specific issues or achieve better outcomes in general. These include, for example:

• Modularization: Breaking down code into small, reusable modules or functions.

• Documentation: Adding meaningful comments and documentation to complex code sections.

• Testability: Writing code that can be easily tested and implementing unit tests.

• Readability: Writing clear and understandable code with meaningful variable names and well-structured control flows.

Examples of Best Practices in Code

To illustrate best practices in code, here are some concrete examples:

1. Modularization:

// Bad practice: One large function that performs many tasks
void processOrder(Order order) {
  // Validation code
  // Calculation code
  // Storage code
  // Notification code
}

// Good practice: Division into smaller, specialized functions
void processOrder(Order order) {
  validateOrder(order);
  calculateTotal(order);
  saveOrder(order);
  notifyUser(order);
}

void validateOrder(Order order) {
  // Validation code
}

void calculateTotal(Order order) {
  // Calculation code
}

void saveOrder(Order order) {
  // Storage code
}

void notifyUser(Order order) {
  // Notification code
}

2. Testability:

// Bad practice: Function that is difficult to test
void processOrder(Order order) {
  if (order.isValid()) {
    // Complex logic here
  }
}

// Good practice: Inject dependencies and make code testable
void processOrder(Order order, OrderValidator validator) {
  if (validator.isValid(order)) {
    // Complex logic here
  }
}

class OrderValidator {
  bool isValid(Order order) {
    // Validation logic here
  }
}

How to Effectively Note Best Practices

In PR reviews, it is important not only to recognize best practices but also to note them constructively and helpfully. Here are some tips on how to do this effectively:

• Provide Positive Feedback: Highlight good practices to reinforce positive behavior.

• Offer Constructive Criticism: Frame criticism in a way that it is understood as a suggestion for improvement rather than an accusation.

• Provide Examples: Show concrete examples or alternatives for how the code can be improved.

• Share Resources: Refer to documentation, articles, or best-practice guides that can help the developer better understand and implement the suggested changes.

By noting and promoting best practices, you contribute to raising the quality of the entire codebase and establishing a higher standard of software development in your team. In the next chapter, we will look at the importance of clear and explicit responses in the PR review process.

Respond Clearly and Explicitly

One of the most important skills in PR reviews is clear and explicit communication. Through precise and constructive feedback, not only is the quality of the code improved, but teamwork is also strengthened. It is crucial that the feedback is clearly understandable and directly addresses the relevant aspects of the code.

The Importance of Clear Communication

Clear communication in the PR review process is important for several reasons:

• Avoid Misunderstandings: Precise feedback prevents misunderstandings and ensures that the developer knows exactly what needs to be changed.

• Increase Efficiency: The clearer the feedback, the faster the developer can make the necessary adjustments, speeding up the entire review process.

• Foster Team Culture: Respectful and constructive feedback contributes to a positive team culture and motivates developers to improve further.

Tips for Precise Feedback

To ensure that your feedback is clear and helpful, you should consider the following tips:

1. Be Specific: Avoid general comments like "The code is not good." Instead, explain exactly which parts of the code need improvement and why.

// General
"The code is not efficient."

// Specific
"The loop in line 23 could be optimized,"
"by using a set instead of a list,"
"to reduce the look-up time."

2. Give Examples: Show concrete examples or alternatives for how the code can be improved.

// Example
"Instead of sorting the list manually, "
"you could use the built-in sort() method, which is more efficient:"
List<String> names = ['Alice', 'Bob', 'Charlie'];
names.sort(); // Built-in sorting method

3. Use Positive Language: Start with positive feedback before moving on to suggestions for improvement. This helps the critique to be received better and motivates the developer.

"The structure of your role is very clear and easy to understand."
"A small improvement would be to make the variable names a bit more descriptive."
"to be designed to further increase readability."

4. Be Respectful and Constructive: Avoid negative or belittling comments. Focus on how the code can be improved and respect the work of others.

// Negative
"This code is poorly written."

// Constructive
"The current approach works, but"
"there is a more efficient way to achieve this."
"Here is a suggestion how it could be done..."

Examples of Good and Bad Feedback

• Bad Feedback:

"That's wrong. Change it."

• Good Feedback:

"The implementation works, but there is a better way," 
"to achieve this. Try using the Map method," 
"to transform the list instead of writing a manual loop." 
"Here is an example..."

Through clear and explicit feedback in the PR review process, you help your team work more efficiently and continuously improve the quality of the code. In the next chapter, we will explore the benefits and best practices for direct comments in code.

Comment Directly in Code

Direct comments in code are a powerful tool in the PR review process. They allow for specific feedback to be given exactly where it is needed, making the review process more efficient and precise. When used correctly, they can significantly improve code quality and clarify misunderstandings.

Advantages of Direct Code Comments

Direct code comments offer several advantages:

• Precision: They allow for feedback to be given directly at the relevant spot in the code, minimizing misunderstandings.

• Context: Comments in the code provide necessary context for the feedback, as the reviewer has the code section directly in front of them.

• Traceability: Later viewers of the code can trace the comments and understand why certain changes were made.

• Efficiency: Developers can implement feedback more quickly, as they know exactly which lines or sections are being referred to.

Direct comments in the code are an essential element of an effective PR review process. In the next chapter, we will discuss the concept of clean code and how to apply this principle in the review process.

A Look at Clean Code

Clean code is a concept aimed at writing code that is easily understandable, maintainable, and extensible. It involves writing clear, consistent, and logical code that can be easily read and understood by other developers. The concept of clean code plays a central role in PR reviews, as it helps ensure the long-term quality and maintainability of the code.

Principles of Clean Code

The principles of clean code encompass various aspects of code design and structuring. Some of the most important principles are:

1. Readability: Code should be easy to read and understand. This includes clear naming conventions, meaningful comments, and logical structure.

2. Consistency: Use consistent styles and conventions throughout the code. This enhances readability and maintainability.

3. Simplicity: Keep the code as simple as possible. Avoid unnecessary complexity and focus on straightforward, clear solutions.

4. Modularity: Break the code into small, reusable modules or functions. This enhances maintainability and reusability of the code.

5. Documentation: Write meaningful comments and documentation to explain complex logic or unusual implementations.

How to Promote Clean Code in the Review Process

To promote clean code in the PR review process, you should pay attention to the following aspects:

1. Clarity and Simplicity:

// Complex and difficult to understand
double calculateComplexValue(double x, double y) {
  return Math.pow((x + y), 2) - Math.sqrt(x * y);
}

// Simpler and clearer
double calculateSumOfSquares(double x, double y) {
  return (x * x) + (y * y);
}

2. Clear Naming: Use meaningful variable and function names.

// Bad naming
double f(double a, double b) {
  return a + b;
}

// Better naming
double addNumbers(double firstNumber, double secondNumber) {
  return firstNumber + secondNumber;
}

3. Modularization:

// Not modular
void processOrder(Order order) {
  // Validation code
  // Calculation code
  // Storage and notification code
}

// Modular
void processOrder(Order order) {
  validateOrder(order);
  calculateOrderTotal(order);
  saveAndNotify(order);
}

void validateOrder(Order order) {
  // Validation code
}

void calculateOrderTotal(Order order) {
  // Calculation code
}

void saveAndNotify(Order order) {
  // Storage and notification code
}

4. Avoid Duplications: Keep the code DRY (Don't Repeat Yourself) by extracting repeated logic into functions or modules.

// Duplicated Code
void sendWelcomeEmail(User user) {
  Email email = new Email(user.email);
  email.subject = "Welcome!";
  email.body = "Welcome to our platform, " + user.name;
  email.send();
}

void sendPasswordResetEmail(User user) {
  Email email = new Email(user.email);
  email.subject = "Password Reset";
  email.body = "Click the link to reset your password.";
  email.send();
}

// DRY principle
void sendEmail(User user, String subject, String body) {
  Email email = new Email(user.email);
  email.subject = subject;
  email.body = body;
  email.send();
}

void sendWelcomeEmail(User user) {
  sendEmail(user, "Welcome!", "Welcome to our platform, " + user.name);
}

void sendPasswordResetEmail(User user) {
  sendEmail(user, "Password Reset", "Click the link to reset your password.");
}

Common Problems and Solutions in Clean Code

1. Long Functions: Long functions are difficult to understand and maintain. Break them down into smaller, focused functions.

// Long function
void processOrder(Order order) {
  if (order.isValid()) {
    calculateTotal(order);
    saveOrder(order);
    notifyUser(order);
  }
}

// Divided into smaller functions
void processOrder(Order order) {
  if (isOrderValid(order)) {
    handleOrderProcessing(order);
  }
}

bool isOrderValid(Order order) {
  // Validation logic
}

void handleOrderProcessing(Order order) {
  calculateTotal(order);
  saveOrder(order);
  notifyUser(order);
}

2. Unclear Comments: Comments should be clear and concise. Avoid unnecessary comments that merely repeat the code.

// Unclear comment
// This method calculates the sum
int add(int a, int b) {
  return a + b;
}

// Clear comment
// Adds two integers and returns the result
int add(int a, int b) {
  return a + b;
}

By applying these principles and best practices in the PR review process, you can ensure that the code not only functions but is also clean, maintainable, and extensible. Clean code is an investment in the future of the project and eases the work for everyone involved. In the next chapter, we will summarize the key points and highlight the importance of good PR reviews for code quality.

Conclusion

A well-conducted PR review process is crucial for the long-term quality and maintainability of a project. By observing code styles, noting best practices, ensuring clear and explicit communication, providing direct comments in code, and focusing on clean code, you can ensure that the code is not only functional but also clean and efficient.

Summary of Key Points

1. Observe Code Styles: Consistent code styles improve the readability and maintainability of code. Tools like linters and formatters help enforce these standards.

2. Note Best Practices: Recognize and promote best practices to continuously improve code quality. Provide constructive feedback and concrete examples.

3. Respond Clearly and Explicitly: Clear communication is vital to avoid misunderstandings and streamline the review process. Be specific and constructive in your feedback.

4. Comment Directly in Code: Use direct comments in code to provide precise and contextual feedback. Tools like GitHub and GitLab effectively support this approach.

5. A Look at Clean Code: Promote the principles of clean code to write maintainable, readable, and extensible code. Pay attention to clarity, consistency, and modularity.

The Importance of Good PR Reviews for Code Quality

Good PR reviews are more than just a means to detect errors. They offer an opportunity for learning, promoting best practices, and strengthening team culture. Through constructive feedback and adherence to standards, not only is the quality of the current code improved, but a foundation is also laid for future developments.

By applying the principles and methods presented here, you can ensure that your team continuously produces high-quality code. This leads to not only better products but also a more efficient and satisfying collaboration within the team.

Encourage your team to implement these tips and continuously improve the PR review processes. In doing so, you contribute significantly to ensuring that the code is robust, clean, and future-proof.